Skip to main content
APIContext
Talk to salesStart free
Start HereGuidesConceptsCLIReferenceChangelogStatus

Troubleshoot expired authentication tokens

An authenticated monitor starts failing, often with a 401 status code, because the credential it sends has expired or been rejected. Use this guide to confirm that the token is the cause, then fix it for the way your token expires: an OAuth 2 refresh token, a Client Credentials grant, a refresh workflow, a credential that never expires, or a certificate.

Prerequisites​

  • The EDITOR role or higher in the project. See Access Roles.
  • The name of the authentication setting and token the failing monitor uses. Open the monitor, expand its Authentication section, and read the Select an Auth Setting and Select a Token lists.

Steps​

1. Confirm the token has expired​

  1. Open Monitor Authentication from Configure Monitoring in the left menu, then click the setting your monitor uses.
  2. In the tokens table, find the token. The Expires column shows the expiry date and time, and the Expires In column shows the time remaining, or Expired once the time has passed. Both columns show Never when APIContext holds no expiry for the token.
  3. Click the token's row to open Edit Token. When the token has an expiry, the Expires badge reads Expired or Active with the date.

APIContext treats a token as expired slightly before its listed time, so that it can renew the token before the API rejects it.

If the token is Active, the cause is probably not expiry: check the username, password, or key the token holds. If it shows Never and the API still rejects it, go to Token shows Never but the API rejects it.

2. Fix the token for its expiry mode​

Open the token and look at its fields to tell which case applies. OAuth 2 tokens show Grant Type, Access Token, Expires In (seconds), and Refresh Token. Tokens on an API key in request / Manual Setup setting, called Manual Setup in this guide, show Headers and Parameters. Basic Auth tokens show Username and Password.

OAuth 2 token with a refresh token​

When a monitor runs and finds the token expired, APIContext sends the Refresh Token to the setting's Get Token URL and saves the new Access Token, the new expiry, and any new Refresh Token the provider returns. You do not need to do anything when this works.

If the token stays expired, the renewal failed. The usual causes are that the provider revoked the refresh token, that it expired, or that a newer one replaced it (some providers issue a new refresh token each time).

  1. On the setting's page, click Edit and check Get Token URL, Client ID, and Client Secret against the app you registered with the provider.
  2. If those are correct, get a new token and point your monitors at it.

OAuth 2 token without a refresh token​

If the Refresh Token field on a token that uses the Authorization Code grant is empty, APIContext cannot renew it. The token works until its expiry, and then the monitor fails until someone signs in again.

  1. Get a new token from the provider and point your monitors at it.
  2. If the provider returns a refresh token during sign-in, APIContext stores it on the new token and renews it automatically from then on. Check the provider's documentation for how to request one.

OAuth 2 token with the Client Credentials grant​

When a monitor finds a Client Credentials token expired, APIContext requests a new token from the Get Token URL using the setting's Client ID and Client Secret. No sign-in is needed.

If the token stays expired, the provider rejected the request.

  1. On the setting's page, click Edit and check Get Token URL, Client ID, and Client Secret.
  2. Click Add New Token, choose Client Credentials as the Grant Type, and click Get Token. If the provider rejects the request, the panel shows its error.
  3. When it succeeds, point your monitors at the new token.

Manual Setup token renewed by a workflow​

A Manual Setup token expires only when a workflow saves an EXPIRES_IN value into it. See Custom authentication. The setting's page shows a Refresh Token Workflow row when one is set.

When a monitor finds the token expired, it stops, APIContext runs that workflow, and the monitor then resumes. APIContext tries the workflow once for each run. If the token is still expired afterward, the monitor runs with the old values and fails.

  1. Run the refresh workflow yourself and open the token afterward. Expires must show a new, later time.
  2. If it does not, check that the workflow saves the new values into this token with a Save Auth Token webhook, and that it saves an EXPIRES_IN value. See Saving variables into an Auth Token.
  3. If the setting shows no Refresh Token Workflow row, APIContext has nothing to run when the token expires. Click Edit on the setting and select the workflow in Refresh Token Workflow.

Token shows Never but the API rejects it​

APIContext records an expiry only when the provider's response includes an expires_in or expires value, or when you enter Expires In (seconds) on the token. Without one, APIContext does not know the token has lapsed and never renews it, even when it holds a refresh token.

  1. Look up the token lifetime in the provider's documentation.
  2. On the setting's page, click Add New Token, then click Enter token values manually. Enter a Name, the Access Token, the Refresh Token if you have one, and the lifetime in Expires In (seconds), then click Save.
  3. Point your monitors at the new token.

API key, fixed bearer token, or Basic Auth​

Tokens on a Manual Setup setting that no workflow updates, and Basic Auth tokens, have no expiry in APIContext, so Expires shows Never. They stop working only when the issuer changes or revokes the credential. Click the token's row, enter the new value in Headers, Parameters, Username, or Password, and click Save. Monitors that use the token pick up the change without further edits. For Basic Auth, see Set up Basic authentication.

Signing key or client certificate​

Certificates for RSA signing and for Mutual TLS are stored once for the organization, and each shows an Expires date on the Certificates tab of your organization settings. The date is highlighted as a warning when 60 days or fewer remain, and as a failure once it has passed. Check this tab before the date arrives.

  1. Select the certificate's row and replace the Certificate and Private Key, as described in Certificates. Update the existing certificate rather than adding a second one, so that settings that already use it keep working.
  2. Allow time for the change. APIContext caches certificates, and a new one can take an hour or more to come into use.

3. Get a new token from the provider​

Do this only when step 2 sends you here.

  1. On the setting's page, click Add New Token.
  2. Enter a Name of at least 3 characters. Choose the Grant Type (normally Authorization Code for user sign-in) and enter the Scope if the provider needs one.
  3. Click Authenticate with followed by the setting's name. The provider's sign-in page opens. The provider may need the Callback URL shown in the panel registered with your app.
  4. Sign in and approve access. The provider returns you to APIContext, which saves the new token.

4. Point monitors at the new token​

Getting a new token from the provider creates a separate token. Monitors keep using the token they have selected until you change it.

  1. Open each monitor that used the old token, expand Authentication, and choose the new token in the list that shows Select a Token.
  2. Save the monitor.

Result​

The failing token's replacement shows a later time in Expires and a remaining time in Expires In, and Edit Token shows Active. After the next run, the monitor's result shows your API's response instead of the authentication failure.

Next steps​