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.
Refresh Token usage
The refresh token can then be exchanged for an access and ID token as follows:
POST /auth/oauth2/token HTTP/1.1
The token endpoint validates the
refresh_token, and checks the user state. If the user is blocked2, an error screen is shown. If all checks are successful, new tokens are issued and returned as a JSON response 1 3:
Your app can now use the received access token to call a Resource Server.
1 This is a simplified example. We omitted irrelevant headers, added line breaks, and truncated tokens to make the example easier to read.
3 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
POST /auth/oauth2/revoke HTTP/1.1
Authorization: Basic base64(client_id:client_secret)
The Authorization header has to contain
client_secret as Basic Auth credentials.
If your application doesn't have a
client_secret, you can send any String as the
This can be tested on the command line using curl as follows:
curl 'https://yourinstance.id.nevis.cloud/auth/oauth2/revoke' -i -X POST \
-H 'Authorization: Basic ZGJkMDBmNjIyYTFmODA1ZjpjbGllbnRfc2VjcmV0X2hlcmVfb3JfYW55X3N0cmluZw==' -d token=$TOKEN
This endpoint validates the
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.