Implementing the Refresh Token Flow

If your access token expires or is revoked, you have two options:

• Initiate the entire authorization flow from the beginning again.
• Use a refresh token to get another access token and refresh token pair.

Refresh tokens are implemented using rotating refresh tokens.

Rotating refresh tokens issue a new, limited life refresh token each time they are used. This mechanism improves on single persistent refresh tokens by reducing the period in which a refresh token can be compromised and used to obtain a valid access token.

Obtaining a Refresh Token

To get a refresh token in your initial authorization flow, add offline_access to the scope parameter of the authorization URL. Once you have the refresh token, exchange it for an access token by calling the token URL.

Exchanging Refresh Tokens for Access Tokens and new Refresh Tokens

Use the following values to construct the request body:

• grant_type: Set to refresh_token.
• client_id: (required) Set this to the Client ID for your app. Find this in Settings for your app in the developer console.
• client_secret: (required) Set this to the Secret for your app. Find this in Settings for your app in the developer console.
• refresh_token: The refresh token that you obtained with your original access token.

1
2
curl --request POST \
  --url 'https://auth.atlassian.com/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{ "grant_type": "refresh_token", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "refresh_token": "YOUR_REFRESH_TOKEN" }'

If successful, a new access token is returned that you use to make calls to the product API. You receive a new refresh token as well and the refresh token you used for the request is disabled.

This is an example response with a refresh token:

1
2
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": <string>,
  "refresh_token": <string>,
  "expires_in": <expiry time of access_token in second>,
  "scope": <string>
}

Troubleshooting

See the list below for possible causes of errors:

• 403 Forbidden with {"error": "invalid_grant", "error_description": "Unknown or invalid refresh token."

  This error is returned for the following reasons:

  • The user's Atlassian account password has been changed. Change the password back to the original password, or initiate the entire authorization flow from the beginning again.
  • Your app is using rotating refresh tokens and the exchange of refresh token failed because:
    • Your refresh token has expired. Users need to initiate the entire authorization flow from the beginning to get a new refresh token.
    • Your app is not replacing the previous refresh token with the new refresh token returned during access token request.