Refresh Token Grant

Refresh tokens are a key component in the OAuth 2.0 authorization framework, enabling the client to obtain a new access token without requiring the resource owner to re-authenticate. In the AgileNow platform, this mechanism ensures that the user does not have to repeatedly log in, providing a smoother user experience.

Requesting a refresh token

To request a refresh token, your application sends a POST request to the /oAuth/rest/v2/Token endpoint on the AgileNow identity platform:

POST /oAuth/rest/v2/Token HTTP/1.1
Host: login.agilenow.io:443
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID

Successful response

A successful response from the server returns a new access token and refresh token:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzIBP...",
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

Error response

An error response (403 Bad Request) indicates that the refresh token is invalid:

{
   "error":"Permission",
   "error_description":"The client application isn't permitted to request a 'refresh_token' code.",
   "Errors": [
     "The client application isn't permitted to request a 'refresh_token' code."
   ],
   "Type": "/Errors/Permission",
   "Title": "Permission",
   "StatusCode": 403,
   "Instance": "/oAuth/rest/v2/Token"
}

Best practices

• Rotation: Regularly rotate refresh tokens. When used, a new one should be issued to maintain security.
• Expiration: Agile.Now refresh tokens are valid for 90 days. Be mindful of this duration when implementing your token strategies.
• Revocation: Enable refresh token revocation, especially if a user logs out, changes their password, or if the token is suspected to be compromised.

By adhering to these best practices and leveraging the refresh token mechanism, you can balance user convenience and security in your Agile.Now platform.