Tokens through 3-legged OAuth authorization

Three-legged OAuth authorization gets its name because in involves three different parties to get you an access token: your application, the ORCID OAuth service, and the user. You can think of it as a method of checks and balances to make sure that your application is what it says it is -- because you clearly identify yourself -- and that the user is who they say they are -- because they clearly identify themselves. This is sometimes referred to as the OAuth dance.

It is used in the ORCID Registry: 

  1. When an organization wants to get a researcher's verified ORCID iD
  2. When an organization wants to read trusted (limited-access) data on a researcher's ORCID record 
  3. When an organization wants to update a researcher's ORCID record

 

The process

Before you can get access token you will need to register your API application and get client credentials. Once registered, you can begin involving the user in an OAuth dance to gain an access token. The token you receive will give you specific privileges, such as reading public and trusted data on the user's ORCID record, or adding and updating data on the user's ORCID record. From the highest level you will

  1. Get the authorization code: Request specific scopes (access privileges) from the user. The user grants access by giving you an authorization code.
  2. Exchange for an access token: Immediately exchange the authorization code for an access token. 
  3. Use the token: The token grants you access to the user's ORCID record. The access must be within the access privileges granted in step 1 above.

Step 1. Get the authorization code

In this first step you will try to get an authorization code by having the user authorize the connection with your system using the oauth/authorize call. (See an example in our tutorial to obtain an authenticate ORCID iD.)

When you use this call, several things happen:

  1. User signs in: The user will be shown the ORCID OAuth authorization screen. This screen shows the user your application's name, a brief description of the application, and the access you are requesting, and asks if it is okay to grant authorization of that access.
  2. User grants (or denies) access: The user will click either the authorize or deny button.
  3. User is sent back to your site: The user will be brought to the redirect URI that you specified in your original call. If the user granted you access, you will get an authorization code; if not, you will receive an error message letting you know that access was denied.

Step 2. Exchange the authorization code for an access token

In this second step you will exchange the authorization code for an access token using the oauth/token call. (See an example in our tutorial to obtain an authenticate ORCID iD.)

When you use this call, you will receive back an access token.

Step 3. Use the token

Once you have an access token you can use it to make one or more API calls. See our tutorials for more information.

URLs for OAuth

Production Registry

Step Member API Public API
Authorize https://orcid.org/oauth/authorize https://orcid.org/oauth/authorize
Exchange https://orcid.org/oauth/token https://orcid.org/oauth/token
Use https://api.orcid.org/v2.0 https://pub.orcid.org/v2.0

Sandbox

Step Member API Public API
Authorize https://sandbox.orcid.org/oauth/authorize https://sandbox.orcid.org/oauth/authorize
Exchange https://sandbox.orcid.org/oauth/token https://sandbox.orcid.org/oauth/token
Use https://api.sandbox.orcid.org/v2.0 https://pub.sandbox.orcid.org/v2.0