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); 
  • Giving a third party that is also a part of your ORCID integration more limited access and/or access for a limited time; 
  • Expiring any existing access and refresh tokens upon user request.

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.


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 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"

Expire the original access token and refresh token, set new access and refresh tokens to quickly expire

This call can be used when you wish to fully expire the existing tokens for the user. For example, if you wish to give the user the power to revoke trusted party permissions from within your own system. Once the original access and refresh tokens are revoked and the new access and refresh tokens expire, your client's permissions will no longer appear in the user's account settings under Trusted Organizations, and they will need to grant new permissions to your client to read or update their ORCID record.

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 "expires_in=10" -d "revoke_old=true"