Refresh Token

A Refresh Token is an opaque string that can be exchanged for an Access Token.

Refresh tokens typically have a long lifetime to avoid that users have to log in frequently. You can configure the lifetime of refresh tokens on the Application settings screen.

Clients may obtain a refresh token by adding the offline_access to the scope query parameter during the Authorization Code or Authorization Code with PKCE flow.

Refresh Token usage

The refresh token can then be exchanged for an access and ID token as follows:

1. Your app sends a request to the Identity Cloud Token endpoint. The grant_type has to be refresh_token, client_id and refresh_token have to be added to the request as POST parameters ¹:

   POST /auth/oauth2/token HTTP/1.1
   grant_type=refresh_token
   &refresh_token=Z1FiWXJZV2...
   &client_id=dbd00f622a1f805f

2. The token endpoint validates the client_id and refresh_token, and checks the user state. If the user is blocked², an error screen is shown. If all checks are successful, new tokens are issued and returned as a JSON response ^{1 3}:

   
   {
     "access_token":"ey...",
     "id_token":"ey...",
     "token_type":"Bearer",
     "expires_in":3600
   }
   

Your app can now use the received access token to call a Resource Server.

¹ This is a simplified example. We omitted irrelevant headers, added line breaks, and truncated tokens to make the example easier to read.

² Users can be blocked on the Management Console.

³ An ID Token is returned only if the scope openid is requested during the initial authentication code flow.

Refresh token revocation

You can revoke refresh and access tokens in case they become compromised. To revoke a refresh or access token, send a request with the token to https://yourinstance.id.nevis.cloud/auth/oauth2/revoke

POST /auth/oauth2/revoke HTTP/1.1
Authorization: Basic base64(client_id:client_secret)

token=Z1FiWXJZV2...

The Authorization header has to contain client_id and client_secret as Basic Auth credentials. If your application doesn't have a client_secret, you can send any String as the client_secret.

This can be tested on the command line using curl as follows:

export TOKEN=ZjNUREZxTEphY0hNaT...
curl 'https://yourinstance.id.nevis.cloud/auth/oauth2/revoke' -i -X POST \
-H 'Authorization: Basic ZGJkMDBmNjIyYTFmODA1ZjpjbGllbnRfc2VjcmV0X2hlcmVfb3JfYW55X3N0cmluZw==' -d token=$TOKEN

This endpoint validates the client_id and client_secret and checks if the token was issued to the application sending the request. If this validation fails, the request is denied, and an error code is returned.

In case of successful validation, the endpoint revokes the token. The revocation takes place immediately, and the token cannot be used again.