Basic tutorial: Get an authenticated ORCID iD

Collecting validated ORCID iDs for individuals through the OAuth process is important. Individuals sign into their ORCID accounts using their registered email address and password (or alternative sign in account) and then authorize your system to obtain their ORCID iD. This ensures you get the correct ORCID iD for the researcher and that the information on that record reflects their research activities.

The tutorial describes the steps to authenticate an ORCID iD. It can be completed using either the public or member API. It reviews the steps to retrieve a verified ORCID iD, which can then be stored in your system’s database. The process for retrieving an ORCID iD follows the OAuth dance as described in Tokens Through 3-legged OAuth Authorization. You can see a basic example of this process from the user point of view in our create on demand demo application.

When trying the example, the text in bold should be replaced with your credentials data and your system responses. For more on how to obtain your credentials, see our getting started guide.

Build the authorization link

The process to get a validated ORCID iD has a user start from your local system. Your system refers the user to a customized ORCID 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 get the ORCID iD. The base 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.

   https://sandbox.orcid.org/oauth/authorize?
   client_id=[Your client ID]&
   response_type=code&scope=/authenticate&
   redirect_uri=[Your landing page]

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-character ORCID iD and read public information on that ORCID record.

/read-limited: Allows the client application to obtain the record holder’s ORCID iD 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.

Exchange the authorization code to get the ORCID iD

You’ll need to sign into an ORCID account -- or create a new one -- and authorize the connection to get the authorization code. After you visit the above link, you will 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://[Your landing page]?code=eUeiz2

Immediately exchange this authorization code to get the validated ORCID iD and an access token  to read the ORCID record. The code expires immediately upon use. An example call:

  https://sandbox.orcid.org/oauth/token (or https://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]

curl example: curl -i -L -H "Accept: application/json" --data "client_id=[Your client ID]&client_secret=[Your client secret]&grant_type=authorization_code&code=[code]&redirect_uri=[Your landing page]" "https://sandbox.orcid.org/oauth/token"

Store the authenticated ORCID iD

The ORCID Registry will return the authenticated ORCID iD when you successfully make the call:

   HTTP/1.1 200 OK
  ...
  {"access_token":"89f0181c-168b-4d7d-831c-1fdda2d7bbbb","token_type":"bearer",
  "refresh_token":"69e883f6-d84e-4ae6-87f5-ef0044e3e9a7","expires_in":631138518,
  "scope":"/authenticate","orcid":"0000-0001-2345-6789","name":"Sofia Garcia "}

The ORCID iD can then be recorded in your system. We also recommend storing the access token in your system to indicate that the ORCID iD has been authenticated and to use to read data on the ORCID record in the future.

Having problems? Check out our troubleshooting guide.