Refresh tokens

Refresh tokens are used to generate additional access tokens. A refresh token is returned with the access token when exchanging an authorization code as part of the two-step and three-step OAuth processes, and it can be used as long as the access token remains active.

The new access tokens can have the same expiration and scopes as the original access token, or can be specified to have a shorter lifespan as well as a smaller subset of scopes from the original access token. New access tokens can be generated in order to replace the original token or generated to serve as an additional token. You can also use refresh token calls to fully expire the original access and refresh tokens and any permissions granted by the user. 

We suggest using refresh tokens in the following conditions:

  • Replacing access tokens that may have been compromised (be sure to revoke the original access token); or 
  • Giving a third party that is also a part of your ORCID integration more limited access and/or access for a limited time.

We recommend that you use the revoke token workflow to revoke an existing access token and its corresponding refresh token. 

Parameters for generating a new access token from a refresh token

Bearer Header Original access token Optional
refresh_token Refresh token Required
client_id Your client iD Required
client_secret Your client secret Required
grant_type refresh_token Required
redirect_uri The redirect uri used with the original token Optional
scope Scopes to include on the new token. Must match or be a subset of the scopes on the original token. Optional; all scopes on the original token will be added to the new token by default.
expires_in The time in seconds the new token will last. Must match or be less than the original token. Optional; new tokens will have the same expiry as the original token by default.
revoke_old true or false Optional; the original access and/or refresh token(s) are simultaneously revoked upon creation of the new token by deault. Use revoke process to fully revoke access tokens.


Example refresh token calls

Refresh an access token without revoking the original access token or refresh token

curl -i -L -k -d "refresh_token=80bf9e0a-39d2-4ac0-ac03-a82a629862bb" -d "grant_type=refresh_token" -d "client_id=APP-NPXKK6HFN6TJ4YYI" -d "client_secret=060c36f2-cce2-4f74-bde0-a17d8bb30a97" -d "expires_in=631136518" -d "revoke_old=false"

Create a second access and refresh token with a smaller scope and faster expiration

This call can be used to create a second access token with a more limited scope or duration, e.g. to be used by a third party that is part of your integration. In this example, the new token will have only the /read-limited scope and will be valid for 1 year.

Note: This call will create a second permission for your API client which is listed under the user's Trusted Organizations list in their account settings.

curl -i -L -k -H"refresh_token=80bf9e0a-39d2-4ac0-ac03-a82a629862bb" -d "grant_type=refresh_token" -d "client_id=APP-NPXKK6HFN6TJ4YYI" -d "client_secret=060c36f2-cce2-4f74-bde0-a17d8bb30a97" -d "scope=/read-limited"  -d "redirect_uri=" -d "expires_in=31557600"

Expire the original access token and refresh token, obtain new access token and refresh token

curl -i -L -k -H "Authorization: Bearer 3bfdc828-af1e-4f11-aa15-8ca0ccf02826" -d "refresh_token=6b9914df-4206-48e7-9f59-902359a2d184" -d "grant_type=refresh_token" -d "client_id=APP-NPXKK6HFN6TJ4YYI" -d "client_secret=060c36f2-cce2-4f74-bde0-a17d8bb30a97"  -d "redirect_uri=" -d "revoke_old=true"