API Tutorial: Get an Authenticated ORCID iD

We recommend that developers test the Public API in the sandbox testing server before using the production version. Below are the steps on how to register for public API credentials in both the Sandbox and Production environments.

• Sign into your ORCID record:
  Production server: https://orcid.org/signin
  Sandbox testing server: https://sandbox.orcid.org/signin
• Click on your name in the top right hand corner
• Click Developer Tools from the menu option
  Note: In order to access Developer Tools, you must verify your email address. If you have not already verified your email address, you will be prompted to do so at this point.
• Click the “Register for the free ORCID public API” button

• Review and agree to the terms of service when prompted.
  

Register an application

• After agreeing to the terms of service, you will be directed back to Developer Tools (https://orcid.org/developer-tools or https://sandbox.orcid.org/developer-tools). Complete the form presented to register a new application.
  • Name: The name of your application. This will be displayed to users when they grant your application permission to get their ORCID iD, and it will be displayed in their Trusted organization list. We recommend using the name of your organization or service (e.g. a journal name).
  • Website: The website the user can visit to learn more about your application. This will be displayed in their Trusted organization list.
  • Description: Information about the application that you are developing and how you will use the user’s ORCID iD. This will be displayed to users on the OAuth screen.

• Redirect URIs: URIs for use with the OAuth 2.0 protocol — these are the locations that your users will be sent to after granting your client permission to get their ORCID iD.
  
  Public API applications must have at least one redirect URI registered, and the URI must begin with https. For testing, you can automatically add Google OAuth Playground URI by clicking “+Google OAuth2 Playground” under Test redirect URIs, or the ORCID Public API Swagger by clicking “+ORCID public swagger interface”.
  For more information, see About redirect URIs.
• Click the Save icon at the bottom of the form to generate your API credentials.

• To view your API credentials, click Show Details.

• Your API credentials – Client ID and Client Secret – are shown just beneath your redirect URIs. Below your credentials are sample URLs and API calls with your credentials pre-filled.

Use your credentials

Now that you have your credentials, it’s time to start using the ORCID Public API!

You can request sandbox Member API credentials to build and test your application. These credentials allow you to make calls to the sandbox member API to read, write to, and update ORCID records. Access to the sandbox testing environment is freely available to anyone, even if you’re not an ORCID member organization.

Note: If you are using a third-party system that already supports ORCID, you may not need to register for sandbox API credentials. 

The sandbox lets you create test user accounts and develop your integration without having to worry about affecting data on the live (production) ORCID Registry. The sandbox behaves the same way as the production ORCID Registry with a few exceptions.

Creating a test account

In order to test the ORCD API and API calls, such as a reading and adding information to an ORCID record, you will also need to create a test ORCID record in the sandbox. This can be done through the user interface, much like on the production ORCID Registry. Go to https://sandbox.orcid.org/register and register for an account.

The sandbox server sends notification emails only to Mailinator (@mailinator.com) email addresses in order to not spam mail servers unintentionally. You will not receive a verification email or password reset notification unless you use a @mailinator.com address, and verification is required in order to make any manual edits to sandbox records. If you do not wish to use a Mailinator address, then please make note of your username and password (as you will be using them to grant authorization to your application when testing), and contact us to request assistance with verification.

Mailinator is a free service that is not managed or maintained by ORCID. We recommend that you review how this service works and its limitations before using these addresses. 

There are different options for registering redirect URIs with your client credentials. Please note that all redirect URIs for your production credentials need to be https. 

Register all redirect URIs fully
This is what is encouraged on the registration form and is what most third parties do.

Register just the host name
If the client app is registered with a redirect uri that is just the host name, then any redirect uri at that host can be used. So, for example if the following redirect uri is registered: https://thirdparty.com

then all of the following redirect_uris will work:

https://thirdparty.com/oauth/callback1
https://thirdparty.com/callback2
https://thirdparty.com/anything-else-as-long-as-the-host-is-the-same

If you decide that this approach might work for you – you can perhaps handle the URIs by registering all of the redirect URIs in one of your domains and then redirect again to the appropriate domain.

Register no redirect uris at all (sandbox only)
If the client app is configured with no redirect_uris, then any redirect_uri can be used. This is less secure than specifying redirect_uris. The redirect_uris give an extra level of security because they prevent somebody using someone else’s stolen client credentials (because we would never redirect to their domain – they would also have to have control over the user’s DNS to get round that!). Because of the potential risks, we only allow this option on the Sandbox API.

When registering for credentials, if you do not want any redirect URIs registered request “no redirect URIs” in the notes field.

If you are using the member API and require any changes to your redirect URIs then please contact our Engagement Team.

Please note that redirects are optional data as part of the OAuth code exchange. If a redirect URI is included then it has to exactly match the one that was used in the authorization URL. For more information please see our other FAQs in this category.

ORCID integrations use “3 legged OAuth” to authenticate users and request permission to interact with their records. Any integration can ask for read permissions using the Public API. ORCID members can use the Member API to ask for update permissions. It works like this:

• You create a special link
• When clicked, the user is sent to ORCID
  • ORCID asks the user to sign in
  • ORCID asks the user to grant permission to your application
  • ORCID sends the user back to your system with an authorization code
• Your system exchanges that code for an access token

The customized authorization URL includes your client information, as well as the ‘scopes’ that specify the specific areas of their record that you wish to access. After signing in, the user authorizes the connection with your system and is returned to your landing page along with an authorization code. This code is then used to get their ORCID iD along with an access token valid for the requested scopes.

Build the authorization link and get and authorization code

You build your authorization link by specifying your API credentials’ client ID and associated landing page (redirect URI). You choose which permissions to ask for by setting the scope parameter.

The below example requests permission to read limited-access data on the ORCID sandbox testing server. In the real world you display this link on your website, or include it in an email when asking the user to authenticate and authorize. However, for testing purposes you can simply paste it into your web browser. Replace the bracketed data with your client information and be sure to remove the square brackets!

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

One the user has clicked the link, signed in at ORCID and granted permissions they are redirected back to your site, like this:

https://[Your landing page]?code=Q70Y3A

Exchange the authorization code for an ORCID iD and access token

You should immediately exchange the authorization code for the ORCID iD and access token. The authorization code expires upon use. The request looks like this and cannot be made in a web browser, it must be made by your server.

 URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  HEADER: Content-Type: application/x-www-form-urlencoded
  METHOD: POST
  DATA: 
    client_id=[Your client ID]
    client_secret=[Your client secret]
    grant_type=authorization_code
    code=Six-digit code
    redirect_uri=[Your landing page]

ORCID will then return the researcher’s authenticated ORCID iD and an access token in JSON format:

{"access_token":"f5af9f51-07e6-4332-8f1a-c0c11c1e3728","token_type":"bearer",
"refresh_token":"f725f747-3a65-49f6-a231-3e8944ce464d","expires_in":631138518,
"scope":"/read-limited","name":"Sofia Garcia","orcid":"0000-0001-2345-6789"}

Access tokens are long lived by default and expire 20 years after issue. The token can be used multiple times before it expires.

Use the access token

3-legged access tokens are linked to specific ORCID record. To use them, you include them in API requests you make to read or update that record.

Implicit OAuth is a lighter weight version of OAuth designed to be used by systems that do not have, or do not want to use server side components. Implicit OAuth can be implemented entirely in the browser using javascript alone. It is available for members and non-members and works like this:

• You create a special link
• When clicked, the user is sent to ORCID
  • ORCID asks the user to sign in
  • ORCID asks the user to grant permission to your application
  • ORCID sends the user back to your system with their ORCID iD, an access token and an id token.
• Your system extracts and stores the authenticated ORCID iD from the response.

For security reasons, when using implicit OAuth, ORCID will not return access tokens with update permissions.

Implicit flow

The implicit flow is designed so that clients do not need to use their secret key to initiate ORCID sign in. Security is enforced by restricting clients to their registered redirect_urls. This lower level of security means that ORCID only supports the /authenticate and openid scopes when using the implicit flow. Tokens are also short lived, with a 10 minute lifespan. This flow is recommended for client side applications which do not have access to a back end server, for example phone applications or single page javascript web-apps.

https://localhost/#access_token=24c11342-f5da-4cf9-94a4-f8a72a30da00&token_type=bearer&expires_in=599&tokenVersion=1&persistent=false&id_token=eyJraWQiOiJxYS1vcmNpZC1vcmctcjlhZmw3cWY2aGNnN2c5bmdzenU1bnQ3Z3pmMGVhNmkiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiMW52bXZBbVdwaVd0Z3ZKZW1DQmVYUSIsImF1ZCI6IkFQUC02TEtJSjNJNUIxQzRZSVFQIiwic3ViIjoiMDAwMC0wMDAyLTUwNjItMjIwOSIsImF1dGhfdGltZSI6MTUwNTk4Nzg2MiwiaXNzIjoiaHR0cHM6XC9cL29yY2lkLm9yZyIsIm5hbWUiOiJNciBDcmVkaXQgTmFtZSIsImV4cCI6MTUwNTk4ODQ2MywiZ2l2ZW5fbmFtZSI6IlRvbSIsImlhdCI6MTUwNTk4Nzg2Mywibm9uY2UiOiJ3aGF0ZXZlciIsImZhbWlseV9uYW1lIjoiRGVtIiwianRpIjoiY2U0YzlmNWUtNTBkNC00ZjhiLTliYzItMmViMTI0ZDVkNmNhIn0.hhhts2-4-ibjXPW6wEsFRaNqV_A-vTz2JFloYn7mS1jzQt3xuHiSaSIiXg3rpnt1RojF_yhcvE9Xe4SOtYimxxVycpjcm8yT_-7lUSrc46UCt9qW6gV7L7KQyKDjNl23wVwIifpRD2JSnx6WbuC0GhAxB5-2ynj6EbeEEcYjAy2tNwG-wcVlnfJLyddYDe8AI_RFhq7HrY4OByA91hiYvHzZ8VzoRW1s4CTCFurA7DoyQfCbeSxdfBuDQbjAzXuZB5-jD1k3WnjqVHrof1LHEPTFV4GQV-pDRmkUwspsPYxsJyKpKWSG_ONk57E_Ba--RqEcE1ZNNDUYHXAtiRnM3w

See our technical documentation for more information.

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It supplements existing OAuth authentication flows and provides information about users to clients in a well described manner.

OpenID connect is a standardised way of implementing OAuth and sharing information about authenticated users. It will now be possible to configure services to use ORCID “out of the box” alongside other standards compliant OpenID connect providers. OpenID connect also provides sharable ID tokens, which are signed objects that can prove a user authenticated using ORCID at a specific time. These tokens can be used by user interface elements to maintain user sessions.

ORCID supports the Basic OpenID Provider conformance profile, which is an extension of the OAuth authorization code flow. ORCID also supports the implicit token flow for the “/authenticate” and “openid” scopes.

This means that ORCID:

• Embeds signed id tokens within token responses for authorization codes generated with the ‘openid’ scope
• Supports the implicit flow when using ‘token’ or ‘token id_token’ response_types and the ‘openid’ scope.
• Supports the ‘prompt’, ‘nonce’ and ‘max_age’ parameters for authorisation requests that include the ‘openid’ scope.
• Supports Openid Connect discovery and userinfo endpoints
• Supports the ‘amr’ field for integrators using the member API for authorisation requests that include the ‘openid’ scope. This can be used to discover if a user authenticated using two factor authentication.

Initiating an OpenID Connect authentication works the same way as a regular OAuth authentication. All that is required is that the client request the ‘openid’ scope If you are using the /authenticate scope replace it with openid, as authenticate and openid have the same authorization only one or the other should be used. If you are using any other scopes, add openid to the list of scopes requested. When the openid scope is included, the Registry will return an id_token inside the token response and grant the client permission to access the user info endpoint for that user.

Note that the ‘openid’ scope does not start with a ‘/’ like the other ORCID API scopes. This is because the ‘openid’ scope is not defined by ORCID, but instead defined by the OpenID Connect specification.

See our technical documentation for more information.

ORCID provides a simple Java Script widget that can be used to obtain authenticated ORCID iDs using OAuth with OpenID Connect.

Please note that the widget uses implicit OAuth, so does not collect any write permissions. This means it is not suitable for member integrations that wish to update records. Please see our tutorial for Adding and Updating data on ORCID records.