Explore the ORCID API with Google OAuth Playground

In real-world situations, API interactions are completed by your system using a programming language such as PHP, Java, or Ruby on Rails. For practice and testing, however, you can interact with the ORCID API using a range of tools capable of making and receiving HTTP requests. Most desktop HTTP tools (such as cURL) are run in the command line; for those who prefer a graphical interface, web-based tools are a useful alternative.

One popular tool is Google's OAuth 2.0 Playground, a free, web-based tool developed and maintained by Google. This tutorial explains how to configure and use the OAuth 2.0 Playground with the ORCID Sandbox Member API.

Note: ORCID does not maintain the OAuth 2.0 Playground - this tool was created by Google, who exclusively maintains its code. While we update this documentation periodically, there may be some inaccuracies from time to time, as we may not be immediately aware of changes to the OAuth 2.0 Playground. Please contact support@orcid.org if you notice errors in this or any support document.


Register for ORCID API credentials

In order to use the ORCID API you will need to register for API credentials. Credentials for the ORCID Development Sandbox, which is used for the examples in this document, are free for anyone. To build an API interaction that works with the production Registry, you will need to become an ORCID member.


Configure the OAuth Playground

The first thing you'll need to do is set up the OAuth 2.0 Playground to work with the ORCID API.

  1. Open a web browser and navigate to https://developers.google.com/oauthplayground

     

  2. Click the gear icon in the upper right corner to open the configuration form.

     

Google OAuth 2.0 Playground Settings

 

  1. In the configuration form, enter the following settings:

     

OAuth flow

Server-side

OAuth endpoints

Custom

Authorization endpoint

https://sandbox.orcid.org/oauth/authorize

Token endpoint

https://sandbox.orcid.org/oauth/token

Access token location

Authorization header w/Bearer prefix

OAuth Client ID

Your assigned client id (ex: APP-F6TMYF419CVYMSNE)

OAuth Client Secret

Your assigned client secret (ex: f40a4c7d-2306-44f1-b8af-a0e464e2bc37)

  1. The configuration screen should look similar to the image below. After you’ve entered the settings, click “Close” in the lower-left corner of the configuration screen.

     

    OAuth 2.0 Configuration
     


Use the OAuth Playground

In order to read from/write to an ORCID record via the API, you first need to get permission from the owner of the record in the form of an Access Token, which can be used to access the user’s record via the API. This process of granting permission is completed using the OAuth 2 authentication protocol and consists of 3 steps:

  1. Get an Authorization Code
  2. Exchange the authorization code for an access token
  3. Use the access token to gain access to the user's ORCID Record

Get an Authorization Code

To get an Authorization Code, you’ll need to prompt the user to log into his/her ORCID account and grant permission to your application. In a real-world situation, this is done using an authorization URL that you construct. With the OAuth Playground, however, this step is done by configuring some additional settings and clicking a button.

  1. First, we will specify the permission (“scope”) that we wish to request from the user, such as the ability to read or add works to his/her record. Beneath “Step 1: Select & authorize APIs” on the left side of the screen, type /orcid-profile/read-limited in the text box (do not select any of the options listed above).

    /orcid-profile/read-limited is a scope that allows you to read a user’s ORCID record, including any items with a privacy setting of “limited”. For a list of scopes used in the ORCID API, see ORCID Scopes

     

  2. Click Authorize APIs

     

  3. An ORCID login screen will appear, requesting that the user grant the permissions that you entered in the previous steps. When this screen appears, click “Sign In,” and sign into the ORCID Sandbox account that you just created.

     

  4. After clicking Authorize on the ORCID login screen, you will be sent back to the OAuth 2.0 Playground and a 6-character code will appear in the Authorization Code field beneath “Step 2: Exchange authorization codes for tokens.”

     

Exchange the Authorization Code for an Access Token

Once you have an Authorization Code, you can exchange it for an Access Token, which allows you to read from/write to a user’s ORCID record. In a real-world situation, this exchange would be done by your system, using a programming language such as PHP, Java, or Ruby on Rails. With the OAuth Playground, however, this step is done by clicking a button.

  1. Beneath the Authorization Code field, Click “Exchange authorization code for tokens.”


     

  2. The token will appear in the Access Token field.

     

  3. Notice in the Request/Response section on the right side of the screen, that you are provided with additional information, such as the name and ORCID iD of the user who granted permission, the lifespan of the token (20 years), and the scope that the token is valid for.


     

Configure Request to API

Now that we have an Access Token, we can use it to perform actions that we requested permission for on the user’s record. In this case, we use the Access Token to read the user’s record. In a real-world situation, this exchange would be done by your system, using a programming language such as PHP, Java, or Ruby on Rails. With the OAuth Playground, however, this step is done by configuring some additional settings and clicking a button.

 

HTTP Method

The HTTP method depends on the action you want to take. For more details on which HTTP method is used for each API action, see ORCID API Calls.

Method Purpose Scopes
GET Retrieve information from an ORCID record /orcid-profile/read-limited, /read-public
POST Add new information to an ORCID record /orcid-works/create, /orcid-bio/external-identifiers/create, /affiliations/create, /funding/create
PUT Update/replace information that you previously added to an ORCID record /orcid-bio/update, /orcid-works/update, /affiliations/update, /funding/update, /webhook

To set the HTTP Method:
 

  1. Click the drop-down menu beside HTTP Method
     
  2. Choose the appropriate method from the list

    HTTP method
     

Add Headers

HTTP headers give the API extra information about your request. There are many types of HTTP headers; in this case, we'll add an accept header to tell the API what format its response should appear in. The ORCID API can return responses in the following formats:

Format Header Value Description
HTML text/html Redirects to the ORCID web user interface to display the result
XML application/vnd.orcid+xml OR application/xml XML conforming to the orcid-message.xsd
JSON application/orcid+json OR application/jsonJavaScript Notation equivalent to the orcid-message.xsd

To add an accept header:
 

  1. Click “Add headers”

     

  2. Enter the following values, then click "Add"
    • Header name: accept
    • Header value: your desired value from the list above
       

     

  3. Click "Close" to close the pop-up
     

Request URI

The Request URI is specifc to the API version and call you are using, as well as the ORCID record you are working with. It consists of the following components:

Request URI

Component Description Value
Base URI The URI for the API version you are using

Public API:   http://pub.orcid.org/

Member API:   https://api.orcid.org/

Sandbox Public API:   http://pub.sandbox.orcid.org/

Sandbox Member API:   http://api.sandbox.orcid.org/

XSD Version ORCID XSD version you are using, from the list in ORCID XSD Information v1.2 (or above)
ORCID iD ORCID iD of the user who granted permission in the "Get an authorization code" step above 16-digit ORCID iD (ex: 0000-0003-1495-7121)
API Call The section of the user's record that you are accessing, from the "Resource" column in ORCID API Calls /orcid-profile, /orcid-works, /orcid-bio, etc

 

  1. Construct a request URI using the components above and enter it in the In the Request URI field.

    For example, to read the record of a sandbox user who had granted your application permission, the request URI is: https://api.sandbox.orcid.org/v1.2/[orcid-id]/orcid-profile

    (replace [orcid-id] with the user's 16-digit ORCID iD)


     

Enter request body

If you are using a PUT or POST method (ie: adding/updating information), enter the XML data you want added to the record using the Request Body section.

  1. Click Request Body
     
  2. In the pop-up that appears, type or paste the XML that you wish to add, entering it as a complete XML document (including the version number).
     
  3. Click Close

Request body
 

Content-Type

If you are using a PUT or POST method to add/update information, you must specify the format of the data you are sending in the Request Body.

  1. Click the drop-down menu beside Content-Type and choose Custom...
     
  2. In the Header Value box beside Content-Type, enter "application/vnd.orcid+xml"
     
  3. Click Add, then click Close

     

The Response

  1. Once you have configured your request, click Send the Request.
     
  2. The request sent by the OAuth Playground and the resulting response from the ORCID API (or an error message if there is a problem with your request) are shown in the Request/Response window. In this example a GET request for /orcid-profile with an XML accept header returns the user's full ORCID record in XML.
     

Request response
 


Example API Requests

These examples provide a quick reference to see the scope and API request fields for various calls.

1. Retrieve an entire ORCID record in XML

Authorization Scope /orcid-profile/read-limited
HTTP Method GET
Add headers Accept: application/vnd.orcid+xml
Request URI https://api.sandbox.orcid.org/[version]/[orcid-id]/orcid-profile
Request Body n/a
Content Type n/a

2. Get an ORCID iD

The ORCID iD will be returned in the Request/Response area after exchanging the Authorization Code for an Access Token. You do not need to complete step 3.

Authorization Scope /authenticate
HTTP Method None. No API Calls are made
Add headers n/a
Request URI None. No API Calls are made
Request Body n/a
Content Type n/a

3. Add an External Identifier

Authorization Scope /orcid-bio/external-identifiers/create
HTTP Method POST
Add headers Accept: application/vnd.orcid+xml
Add headers Content-Type: application/vnd.orcid+xml
Request URI https://api.sandbox.orcid.org/[version]/[orcid_id]/orcid-bio/external-identifiers
Request Body An External Identifier in ORCID Messages XML, see XML for orcid-bio External Identifier
Content Type Custom (defined in the header with content-type:application/vnd.orcid+xml)

4. Update a Biography in XML

Authorization Scope /orcid-bio/update
HTTP Method PUT
Add headers Accept: application/vnd.orcid+xml
Add headers Content-Type: application/vnd.orcid+xml
Request URI https://api.sandbox.orcid.org/[version]/[orcid-id]/orcid-bio
Request Body

An ORCID Profile in XML (See XML for orcid-bio for more about creating/editing a profile in XML)

Content Type Custom (defined in the header with content-type:application/vnd.orcid+xml)

5. Add a Work in XML

Authorization Scope /orcid-works/create
HTTP Method POST
Add headers Accept: application/vnd.orcid+xml
Add headers Content-Type:application/vnd.orcid+xml
Request URI https://api.sandbox.orcid.org/[version]/[orcid-id]/orcid-works
Request Body A work, see XML for orcid-works
Content Type Custom (defined in the header with content-type:application/vnd.orcid+xml)

6. Update All Works in XML

This command will delete all existing works and replace them with the updated works you upload

Authorization Scope /orcid-works/update
HTTP Method PUT
Add headers Accept: application/vnd.orcid+xml
Add headers Content-Type:application/vnd.orcid+xml
Request URI https://api.sandbox.orcid.org/[version]/[orcid-id]/orcid-works
Request Body All works, see XML for orcid-works
Content Type Custom (defined in the header with content-type:application/vnd.orcid+xml

7. Add Affiliations in XML

Authorization Scope /affiliations/create
HTTP Method POST
Add headers Accept: application/vnd.orcid+xml
Add headers Content-Type:application/vnd.orcid+xml
Request URI https://api.sandbox.orcid.org/[version]/[orcid-id]/affiliations
Request Body An affiliation, see XML for Affiliations
Content Type Custom (defined in the header with content-type:application/vnd.orcid+xml)
 

8. Updating Affiliations in XML

Authorization Scope /affiliations/update
HTTP Method PUT
Add headers Accept: application/vnd.orcid+xml
Add headers Content-Type:application/vnd.orcid+xml
Request URI https://api.sandbox.orcid.org/[version]/[orcid-id]/affiliations
Request Body All affiliations, see XML for Affiliations
Content Type Custom (defined in the header with content-type:application/vnd.orcid+xml)