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.

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.

Build the authorization call

During the three-legged token exchange, your system refers the user to a customized authorization call, a URL that includes your client information. The user authorizes the connection with your system and is returned to your landing page (redirect URI) along with an authorization code that you’ll use to obtain the ORCID iD and access token. The call's URL is the same whether you are using the public or member API.

The below example uses sandbox member API credentials. It can be pasted directly into your web browser. Be sure to change the client ID and redirect URI to reflect those registered to your account and remove the brackets.

Resource URL:

Sandbox: https://sandbox.orcid.org/oauth/authorize
Production Registry: https://orcid.org/oauth/authorize

Client ID:

This is the unique client ID for your public or member API client. For more on getting API credentials, see our Getting Started Guide.

Response:

code
(This option does not change)

Scope:

The permission of access requested by the organization or application. Both public and member API can use /authenticate. Member API clients have access to additional scopes to read-limited information or write to an ORCID record. 

/authenticate: Allows the client application to obtain the record holder's 16-digit identifier and read public information on that ORCID record.

/read-limited: Allows the client application to obtain the record holder’s 16-digit identifier and read public and limited access information on that ORCID record.

The full list of available scopes are in the ORCID GitHub repository.

Redirect URI:

The landing page to which the individual will be directed after authorizing the connection. The redirect URI should match one of those specified in your client credentials.

Example call

   https://sandbox.orcid.org/oauth/authorize?
   client_id=APP-NPXKK6HFN6TJ4YYI&
   response_type=code&scope=/authenticate&
   redirect_uri=https://developers.google.com/oauthplayground/

The user will sign into their ORCID account -- or create a new one -- and authorize the connection. They will then be returned to the specified redirect URI. Attached to the end will be a 6-character authorization code appended to the end of that URL:

https://developers.google.com/oauthplayground/?code=eUeiz2

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. 

When you use this call, you will receive back an access token. Note that the authorization code exchange can be performed only once. If the same authorization code is used twice to obtain an access token, then 1) the authorization code exchange will fail, and 2) the access token and refresh token originally obtained from the token exchange will be revoked by the ORCID Registry. 

Formatting the call

  https://sandbox.orcid.org/oauth/token
  METHOD: POST
  HEADER: accept:application/json
  DATA: 
    client_id=[Your client ID]
    client_secret=[Your client secret]
    grant_type=authorization_code
    code=[Code from previous step]
    redirect_uri=[Your landing page]

Example call

curl -i -L -H "Accept: application/json" --data "client_id=APP-NPXKK6HFN6TJ4YYI&client_secret=060c36f2-cce2-4f74-bde0-a17d8bb30a97&grant_type=authorization_code&code=eUeiz2&redirect_uri=https://developers.google.com/oauthplayground/" "https://sandbox.orcid.org/oauth/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 what calls are possible.

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

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