OAuth2 token lifecycle and required scopes

Use this reference to understand how watsonx Orchestrate stores and refreshes OAuth2 access tokens for tool connections. OAuth scopes are required for specific catalog tools, and what to do when a tool stops working after its initial token expires.

How watsonx Orchestrate manages OAuth2 tokens

When a user authorizes an OAuth2 connection through the watsonx Orchestrate UI, the platform performs the authorization code exchange and stores two tokens on behalf of that user:

Token	Purpose	Lifetime
`access_token`	Passed directly to the downstream tool on every invocation	Short-lived (typically 1–60 minutes, provider-specific)
`refresh_token`	Used by Orchestrate to silently obtain a new `access_token` when the current one expires	Long-lived (days to months, or until revoked)

On each tool invocation, watsonx Orchestrate checks whether the stored access_token is still valid. If it is expired, watsonx Orchestrate automatically calls the provider’s token endpoint with the stored refresh_token to obtain a new access_token, then retries the tool call, without requiring to reauthorize.

OAuth-based connections currently work when the user interacts with the agent through the watsonx Orchestrate UI (not embedded web chat). See Why use connections for a full compatibility matrix.

Refresh tokens are issued when `offline_access` is requested

The most common reason that a tool works initially but stops working after the first token expiry is a missing refresh token. OAuth2 providers issue a refresh_token when the authorization request explicitly includes the offline_access scope (or an equivalent provider-specific scope). If offline_access is omitted, the provider issues an access_token with no way to renew it. When that token expires, every subsequent tool call fails with an authentication error. Make sure the offline_access scope is included in your connection’s scope list at the time of initial authorization. Adding it after the fact requires the user to reauthorize the connection from the beginning. You cannot back-fill a refresh token.

Required scopes by catalog tool

The following table lists the minimum scopes required for common catalog integrations. Scopes marked required for refresh must be included or the connection will stop working after the first access_token expiry.

Tool	Required scopes	Notes
Jira	`read:jira-work`, `write:jira-work`, `offline_access`	`offline_access` is required for refresh. Atlassian doesn’t issue a refresh token without it.
Salesforce	`api`, `refresh_token` or `offline_access`	Salesforce uses `refresh_token` as the scope name. Both `refresh_token` and `offline_access` are accepted, include at least one.
GitHub	`repo`, `offline_access` (if supported by your GitHub App)	GitHub does not support `offline_access` on the standard OAuth App flow. Use a GitHub App with fine-grained tokens and a long expiry, or reauthorize when the token expires.
Other tools	Consult the provider’s OAuth2 documentation	Look for a scope named `offline_access`, `offline`, or `refresh_token`.

Jira refresh tokens require offline_accessAtlassian’s OAuth 2.0 (3LO) implementation does not issue a refresh token unless offline_access is explicitly included in the scope list at authorization time. If this scope is missing, the connection will appear good until the initial access_token expires (after one hour), at which point every Jira tool call will return an authentication error.Make sure the offline_access scope in the Atlassian Developer Console is enabled, and pass it in the --scope flag when you set credentials:

BASH

orchestrate connections set-credentials -a jira \
  --env draft \
  --client-id '<client_id>' \
  --client-secret '<client_secret>' \
  --authorization-url 'https://auth.atlassian.com/authorize' \
  --token-url 'https://auth.atlassian.com/oauth/token' \
  --scope 'read:jira-work write:jira-work offline_access'

Setting scopes when configuring an OAuth connection

Scopes are set as part of the set-credentials step for any auth-code or password flow connection. Pass a space-separated list of scope values to the --scope flag:

BASH

orchestrate connections set-credentials -a <app_id> \
  --env draft \
  --client-id '<client_id>' \
  --client-secret '<client_secret>' \
  --authorization-url 'https://provider.example.com/oauth/authorize' \
  --token-url 'https://provider.example.com/oauth/token' \
  --scope '<scope1> <scope2> offline_access'

When you import from a YAML file, scopes are stored as part of the connection credentials, not the YAML spec itself. The YAML file defines the connection structure. You still run set-credentials separately to supply the scope list and other sensitive values.

There is no dedicated “Scopes” field in the Connections Management UI. Scopes are configured exclusively through the CLI set-credentials command. If you need to change the scope list for an existing connection, rerun set-credentials with the updated --scope value and then have each affected user reauthorize the connection.

What happens when a token expires

Situation	Outcome
`access_token` expires, refresh token present	watsonx Orchestrate silently renews the `access_token` and retries the tool call. The user sees no interruption.
`access_token` expires, no refresh token	The tool call fails. The user sees an authentication error in the chat UI.
`refresh_token` itself expires or is revoked	watsonx Orchestrate cannot renew the `access_token`. The tool call fails with an authentication error.
Connection reauthorized with incorrect scopes	A new access token is issued but without `offline_access`, so the cycle repeats after the next expiry.

Troubleshooting: tool stops working after initial authorization

If a tool that was working correctly starts returning authentication errors, follow these steps:

Check whether a refresh token was issued

The most common root cause is a missing offline_access scope on the original authorization. Review the scope list in your connection credentials:

BASH

orchestrate connections list

Inspect the connection’s configured scopes. If offline_access (or the provider-equivalent) is absent, proceed to step 2.

Update the scope list

Rerun set-credentials with the corrected scope list, including offline_access:

BASH

orchestrate connections set-credentials -a <app_id> \
  --env draft \
  --client-id '<client_id>' \
  --client-secret '<client_secret>' \
  --authorization-url 'https://provider.example.com/oauth/authorize' \
  --token-url 'https://provider.example.com/oauth/token' \
  --scope '<existing_scopes> offline_access'

Re-authorize the connection

Updating the scope list alone is not sufficient, the provider issues a refresh token during the authorization flow. Each user who holds the connection must reauthorize it:

From the main menu in the watsonx Orchestrate UI, go to Manage > Security > Connections
Locate the affected connection and click the overflow menu icon and select Edit connection.
Click Connect now.
Complete the OAuth consent screen, ensuring the updated scopes are shown.

After re-authorization, watsonx Orchestrate stores the new access_token and if offline_access was included, the refresh_token. Subsequent token renewals will happen silently.

Verify the fix

Run a test invocation of the affected tool from the agent chat UI. If the call succeeds, the refresh token is in place. If it fails again, check that the OAuth app in the provider’s developer console has offline_access enabled as an allowed scope.

Token storage and security

watsonx Orchestrate stores access tokens and refresh tokens encrypted at rest, scoped to the individual user and connection. Tokens are never shown in logs, the CLI output, or the UI. They are decrypted in memory at the moment that a tool call is dispatched to the downstream service. For team connections, the builder’s credentials (including the refresh token) are shared across all users of the agent. For member connections, each user holds their own token pair and must authorize the connection individually.

Release Notes

Get Started

Build

Deploy

Analyze

Developer experience

Legal notices

How watsonx Orchestrate manages OAuth2 tokens

Refresh tokens are issued when `offline_access` is requested

Required scopes by catalog tool

Setting scopes when configuring an OAuth connection

What happens when a token expires

Troubleshooting: tool stops working after initial authorization

Token storage and security

​How watsonx Orchestrate manages OAuth2 tokens

​Refresh tokens are issued when offline_access is requested

​Required scopes by catalog tool

​Setting scopes when configuring an OAuth connection

​What happens when a token expires

​Troubleshooting: tool stops working after initial authorization

​Token storage and security

​Related pages

How watsonx Orchestrate manages OAuth2 tokens

Refresh tokens are issued when `offline_access` is requested

Required scopes by catalog tool

Setting scopes when configuring an OAuth connection

What happens when a token expires

Troubleshooting: tool stops working after initial authorization

Token storage and security

Related pages