This boot camp provides a hands-on tutorial for using the ORCID Member and Public APIs.
--2. Public API: Searching & Retrieving ORCID Records
3. Public API: Searching & Retrieving ORCID Records
3.1 Retrieving Public Record Data
3.2 Searching Public Record Data
4. Public API: Getting Authenticated ORCID iDs
5. Member API: Access to amend ORCID records
6. Member API: Getting permission to edit ORCID records
7. Member API: Writing to ORCID records via the API
8. Member API: Creating New Records
8.1 Construct the Authorization URL
8.2 Build a Redirect Page/Application
8.3 Prompt Users to Create or Connect their ORCID iD
ORCID offers several APIs (Application Programming Interfaces) that allow your systems to connect to the ORCID registry, including reading from and writing to ORCID records. Some API functions are freely available to anyone; others are available to organizations that financially support ORCID with an annual membership subscription.
API Version |
Access |
Features |
Public API |
Freely available to anyone |
Authenticate: Obtain a user’s authenticated ORCID iD |
Member API |
Available to organizations that support ORCID with an annual membership subscription |
Read (Limited): Search/retrieve limited-access data |
In addition to the production Registry and APIs, ORCID also offers a testing environment, the ORCID Sandbox, which we will be using for this boot camp. The Sandbox is open to all users and provides a place to develop and test applications without affecting data in the live ORCID registry.
The Sandbox includes:
- Sandbox Registry: Simulates the ORCID Registry
- Sandbox Member API: Simulates the Member API
- Sandbox Public API: Simulates the Public API
The sandbox behaves the same way as the production ORCID Registry with a few exceptions:
- Search & Link tools do not function.
- To avoid unintentional spamming, the Sandbox sends emails only to @mailinator.com addresses. Mailinator.com is an inbox testing service that is free and requires no registration. To receive emails from the Sandbox, use an @mailinator.com email address when creating Sandbox record(s).
- Links in the top menu bar (For Researchers, For Organizations, About, etc.) do not function.
All of the ORCID APIs are based on the same set of technologies:
- REST: ORCID APIs are “RESTful”, which means that they use HTTP (hyper-text transfer) calls to transfer information.
- OAuth: ORCID APIs use the OAuth 2.0 authentication protocol in order to grant client applications access to users’ ORCID records.
- XML/JSON: ORCID APIs support data exchange in either XML or JSON format.
In order to use the ORCID APIs you will need the following software tools:
- Web browser: Firefox (33+), Chrome (38+), Internet Explorer (10+), Safari (6+)
- Internet connection
- Plain text editor: TextEdit (Mac), Notepad++ (Win), or your preferred plain text editor
- Software capable of making HTTP requests:
- cURL: free, command-line application available for Mac or Windows at http://curl.haxx.se/download.html (pre-installed on most Mac OS versions; accessible within Terminal application)
- Online tools, e.g. hurl.it or Google OAuth Playground
- Your own web application, in a language such as Java, Ruby, Python, PHP, etc.
For this boot camp, we will be using the online tool Google OAuth Playground.
In order to try out API calls, such as a reading a record and adding information to it, you will also need to create a test ORCID record in the Sandbox. This can be done through the user interface, much like in the live ORCID registry.
- Open a web browser and navigate to https://sandbox.orcid.org/signin
- Click Register for an ORCID iD.
- Complete the form with a name, email, and password.
- Click the I consent… checkbox and click Register.
- After completing the registration process, you will be taken to your new Sandbox ORCID record. Make note of the 16-digit ORCID iD for this record – you will need this in order to make API calls later during the boot camp.
- Add a few pieces of information to your new Sandbox record – biography, education, employment, etc. – so that you have some data to work with in future steps.
IMPORTANT! Don’t use a real email address! Instead, make up an address ending in @mailinator.com (use any prefix, e.g. [email protected]).
Access to the ORCID Public API requires a set of credentials consisting of a Client ID and a Client Secret. Public API credentials are tied to an individual's ORCID record and cannot be transferred to another person. The process for getting Public API credentials is identical in the sandbox and production environments.
- To access the Public API, you’ll first need to verify your email address. Visit http://mailinator.com/ and enter the email that you used to create your Sandbox account.
- Open the confirmation message from ORCID and click Verify your email address.
- Back in your ORCID account, click Developer Tools at the top of the screen.
- Click the Register for the free ORCID public API button.
- Review and agree to the terms of service when prompted.
- In the form that appears, enter the following values:
- 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. We’ll be using these later in the boot camp, but no need to copying them down – they are always available in the Developer Tools section of your account.
Name |
Name of the ORCID application that you are developing. Ex: State University ORCID Connector |
Website |
URL for the homepage of your ORCID application. |
Description |
Description of the ORCID application that you are developing. Ex: An application that allows users to connect their ORCID iD to their State University faculty profile. |
Redirect URIs |
URIs for use with the OAuth 2.0 protocol; for more information, see About redirect URIs. For this boot camp, use: https://developers.google.com/oauthplayground/ (Add this URI automatically by clicking "+Google OAuth2 Playground" under Test redirect URIs.) |
Using the Public API, you can retrieve the XML version of any user’s public ORCID record. This is same information that you’ll see by viewing a record in the user interface of the ORCID registry, but in machine-readable XML format. In a real-world web application, this process can be used to retrieve and copy information from ORCID records into your own system.
Visit https://developers.google.com/oauthplayground/
- Beneath Step 3: Configure request to API on the left side of the screen, set HTTP Method to GET.
- Click Add headers and enter the following values:
- Header name: Accept
- Header value: application/vnd.orcid+xml
In the Request URI field, enter https://pub.sandbox.orcid.org/v1.2/[orcid-id]/orcid-profile, replacing [orcid-id] with the ORCID iD of the Sandbox record that you created earlier (ex: https://pub.sandbox.orcid.org/v1.2/0000-0002-1223-3173/orcid-profile).
- Leave the Request Body and Content-Type fields blank, and click Send the request.
- The XML for the ORCID record that you requested will appear in the Request/Response section on the right side of the screen.
In addition to retrieving an individual’s entire ORCID record, the Public API can be used to search for all records whose public data contain particular search terms.
Note that only a portion of the ORCID record is returned for each matching result. To view the entire record, use the Public API to retrieve the record, as in section 3.1.
This tutorial provides a very brief introduction to searching with the API. For much more information, see https://members.orcid.org/api/tutorial-searching-api-12-and-earlier
A basic keyword search performs a full-text search of all publicly-visible information in users’ ORCID records (Names, ORCID iDs, and any other data with a privacy setting of “Everyone”).
- Visit https://developers.google.com/oauthplayground/
- Beneath Step 3: Configure request to API on the left side of the screen, enter the following:
- Leave the Request Body and Content-Type fields blank, and click Send the request.
- XML for matching records appears in the Request/Response section on the right.
HTTP Method |
GET |
Add Headers |
Header name: Accept |
Request URI |
https://pub.sandbox.orcid.org/v1.2/search/orcid-bio?q=newman |
In addition to the basic keyword search, multiple keywords keywords can be included using Boolean terms “AND” or “OR”. Exact phrases can be included using quotation marks. Note that “+” signs must be substituted for spaces and that Boolean terms must be uppercase.
- Beneath Step 3: Configure request to API on the left side of the screen, enter the following:
- Leave the Request Body and Content-Type fields blank and click Send the Request.
- XML for matching records appears in the Request/Response section on the right.
HTTP Method |
GET |
Add Headers |
Header name: Accept |
Request URI |
http://pub.sandbox.orcid.org/v1.2/search/orcid-bio?q=michael+AND(hkbu+OR+"Hong+Kong+Baptist+University") |
For more specific results, search for terms in particular record fields rather than entire ORCID records.
Available search fields include:
- ORCID iD
- Names (Given Names, Family Name, Credit Name, Other Names)
- Email address
- Work Titles
- External Identifiers (DOIs, PMIDs, etc.)
- Creation/Last Modified Dates
For a complete list, see http://members.orcid.org/api/tutorial-searching-api-12-and-earlier
- Beneath Step 3: Configure request to API on the left side of the screen, enter the following:
- Leave the Request Body and Content-Type fields blank, and click Send the request.
- XML for matching records appears in the Request/Response section on the right.
HTTP Method |
GET |
Add Headers |
Header name: Accept |
Request URI |
https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?q=family-name:Sanchez |
- Search for records associated with the exact DOI 10.1087/20120404:
https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?q=digital-object-ids:%2210.1087/20120404%22
- Search for records modified between May 6, 2015 and today:
https://pub.sandbox.orcid.org/search/orcid-bio?q=profile-last-modified-date:%5B2015-05-06T00:00:00Z%20TO%20NOW%5D
When you need to collect a user’s ORCID iD in your web application, the best method is to use the ORCID API to get an authenticated ORCID iD.
Rather than relying on users to correctly type their ORCID iDs into a form, the API process prompts users to log into their ORCID account and passes their ORCID iD to your system automatically. This prevents typos and ensures that you get the correct ORCID iD for each user.
Getting an authenticated ORCID iD through the API depends on an authentication process called OAuth. With OAuth, a user can authorize a third-party system to access their account in another system without sharing their login information.
You’ve likely encountered OAuth many times before – it’s the same technology that allows you to log into other applications using your Google, Facebook, or Twitter account.
The OAuth process consists of the following steps:
- Get an Authorization Code from the user.
- Exchange the Authorization Code for the user’s ORCID iD.
In a real-world situation, API interactions are completed by your system using a programming language such as PHP, Java, or Ruby on Rails. For this boot camp, however, we’ll be using a web-based tool, the Google OAuth Playground.
The first thing we need to do is set up the OAuth Playground to work with the ORCID API.
- Visit https://developers.google.com/oauthplayground
- Click the gear icon in the upper right corner to open the configuration form.
In the configuration form, enter the following:
- The configuration screen should look similar to the image at right. After you’ve entered the settings, click Close in the lower-left corner of the configuration screen.
OAuth flow |
Server-side |
OAuth endpoints |
Custom |
Authorization endpoint |
|
Token endpoint |
|
Access token location |
Authorization header w/Bearer prefix |
OAuth Client ID |
Your Public API client id (ex: APP-AWPNRAQNO2Y0K3AC) |
OAuth Client Secret |
Your Public API client secret (ex: 63a7f233-2277-4364-9745-4d5f4b5a0360) |
To get an Authorization Code, you’ll need to prompt the user to log into their 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.
First, we will specify the permission (scope) that we wish to request from the user.
- Click Authorize APIs.
An ORCID OAuth login screen will appear, requesting that the user grant the permissions entered in the previous steps. When this screen appears, click Sign In, and sign into your Sandbox account.
- Click Authorize on the ORCID OAuth login screen and you will be sent back to the OAuth Playground. A 6-character code will appear in the Authorization Code field beneath Step 2: Exchange authorization codes for tokens.
Do not select any of the options from the list beneath Step 1: Select & authorize APIs. Instead, type /authenticate in the text box.
The /authenticate scope allows you to retrieve a user’s ORCID iD. This is the only scope available in the Public API. The Member API, however, permits additional scopes, which we’ll explore in the next section.
Once you have an Authorization Code, you can exchange it for the user’s ORCID iD. 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.
Beneath the Authorization Code field, click Exchange authorization code for tokens.
- The user’s name and ORCID iD will appear in the Request/Response section on the right side of the screen.
As discussed in section 1.1, the Public API can only be used to read and search ORCID records, and to get authenticated ORCID iDs. The Member API, however, can be used to add new information to ORCID records, as well as to update information previously added.
As with the Public API, client credentials consisting of a client ID and a client secret are needed in order to access the Member API. Public API credentials cannot be used to access the Member API, so we’ll be using a different client ID and secret for the remainder of this boot camp.
Client Credentials for the Member APIs are issued by ORCID. For this boot camp, you can use the sample Sandbox Client Credentials, but we recommend that you obtain your own Sandbox Client Credentials using the request form at http://orcid.org/content/register-client-application
We’ll continue to use the Google Developers’ OAuth Playground for the next exercises, but a few configuration changes are needed in order to work with the Member API.
- Visit https://developers.google.com/oauthplayground
- Click the gear icon in the upper right corner to open the configuration form.
- Enter the following:
(Fields edited to work with the Member API are highlighted; the rest remain the same.)
OAuth flow
Server-side
OAuth endpoints
Custom
Authorization endpoint
Token endpoint
Access token location
Authorization header w/Bearer prefix
OAuth Client ID
Your Member API client ID (ex: APP-E422WM33OPZWKKMQ)
OAuth Client Secret
Your Member API client secret (ex: ae857cfb-446b-4c3f-8a09-55436bf602dc)
- The configuration screen should look similar to the image at right. After you’ve entered the settings, click Close in the lower left corner of the configuration screen.
To access an ORCID record via the Member API, you first need to get permission from the owner of the record in the form of an Access Token.
This process of granting permission uses OAuth and is similar to the process used for obtaining an authenticated ORCID iD described in section 4.
- Get an Authorization Code.
- Exchange the Authorization Code for an Access Token.
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.
- Beneath Step 1: Select & authorize APIs on the left side of the screen, type /orcid-works/create in the text box (do not select any of the options in the box above).
- Click Authorize APIs.
An ORCID OAuth login screen will appear. Click Sign In and sign into your Sandbox account.
- Click Authorize on the ORCID OAuth login screen and you will be sent back to the OAuth Playground. A 6-character code will appear in the Authorization Code field.
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.
Beneath the Authorization Code field, click Exchange authorization code for tokens.
- The token will appear in the Access Token field.
- Note that you are provided with additional information in the Request/Response section on the right side of the screen, such as the name and ORCID iD of the user who granted permission, the lifespan of the token (20 years), and the scope for which the token is valid.
- Beneath Step 3: Configure request to API, set HTTP Method to POST.
- Click Add headers and enter the following values:
- Header name: accept
- Header value: application/vnd.orcid+xml
- Click Add to add another header and enter the following values:
- Header name: Content-type
- Header value: application/vnd.orcid+xml
- Click Add again, then click Close.
- In the Request URI field, enter https://api.sandbox.orcid.org/v1.2/[orcid-id]/orcid-works, replacing [orcid-id] with the ORCID iD of the Sandbox record that you created earlier (ex: https://api.sandbox.orcid.org/v1.2/0000-0002-3791-8427/orcid-works)
- Click Enter request body. Here is where you’ll enter the XML for the works you wish to add.
- Visit http://git.io/vITI9 and copy the XML in the Sample Work section.
- Paste the copied content into the Request Body text box and click Close.
- Click Send the request.
- The results will appear in the Request/Response section on the right side of the screen. Scroll to the bottom – if you see HTTP/1.1 201 Created, the work was successfully posted!
- Visit the public view of your Sandbox record at http://sandbox.orcid.org/[Your sandbox iD] to see the work that you added in the user interface.
In the last section, we asked the user for permission to add a new work to their ORCID record using the /orcid-works/create scope. To edit that same work, we need to request permission using the /orcid-works/update scope.
In a real-world situation, create and update permissions can be requested in the same step, resulting in an Access Token that can be used to both add and edit works. When using the OAuth Playground, however, we can only request permission for one scope at a time, so we’ll need to generate a new Access Token in order to edit the work that we just added.
- Beneath Step 1: Select & authorize APIs, type /orcid-works/update in the text box.
- Click Authorize APIs.
- An ORCID OAuth login screen will appear. Click Sign In, and sign into your Sandbox account.
- Click Authorize on the ORCID OAuth login screen and you will be sent back to the OAuth Playground. A 6-character code will appear in the Authorization Code field.
- Beneath the Authorization Code field, click Exchange authorization code for tokens.
- The token will appear in the Access Token field.
- Beneath Step 3: Configure request to API, set HTTP Method to PUT.
- Click Add headers and enter the following values:
- Header name: Accept
- Header value: application/vnd.orcid+xml
- Click Add to add another header and enter the following values:
- Header name: Content-type
- Header value: application/vnd.orcid+xml
- Click Add again, then click Close.
- In the Request URI field, enter https://api.sandbox.orcid.org/v1.2/[orcid-id]/orcid-works, replacing [orcid-id] with the ORCID iD of your Sandbox record (ex: https://api.sandbox.orcid.org/v1.2/0000-0002-1223-3173/orcid-works).
- Click Enter request body. This is where you’ll enter the XML for the work that you wish to edit.
- Visit http://git.io/vITI9 and copy the XML in the Sample Work Updated section.
- Paste the copied content into the Request Body field and click Close.
- Click Send the Request.
- The results will appear in the Request/Response section on the right side of the screen. If the full XML of the user’s record appears, the work was successfully updated!
If you receive an error, be sure to check that the headers value under Add headers have not been changed to garbled text, e.g. "application%2Fvnd.orcid%2Bxml".
- Visit the public view of your Sandbox record at http://sandbox.orcid.org/[Your sandbox iD] to see the changes to the work in the user interface.
In this section we will add and update an employment affiliation to your Sandbox test ORCID record using the permission that you have already received from the earlier exercise. Note: It is also possible to post an education affiliation using [different slightly different XML and endpoints](sample-education-affiliation.xml).
- Beneath Step 3: Configure request to API, set HTTP Method to POST.
- Click Add headers and enter the following values:
- Header name: accept
- Header value: application/vnd.orcid+xml
- Click Add to add another header and enter the following values:
- Header name: Content-type
- Header value: application/vnd.orcid+xml
- Click Add again, then click Close.
- In the Request URI field, enter https://api.sandbox.orcid.org/v2.0/[orcid-id]/employment, replacing [orcid-id] with the ORCID iD of the Sandbox record that you created earlier (e.g. https://api.sandbox.orcid.org/v2.0/0000-0002-3791-8427/employment)
- Click Enter request body. Here is where you’ll enter the XML for the works you wish to add.
- Copy the XML.
- Paste the copied content into the Request Body text box.
- Customize the text to reflect your institution. For the disambiguated-organization-identifier, replace XXXXXX with the Ringgold identifier for your institution.
- Click Close.
- Click Send the request.
- The results will appear in the Request/Response section on the right side of the screen. Scroll to the bottom – if you see HTTP/1.1 201 Created, the affiliation was successfully posted!
- Each item added to the ORCID record has a unique put-code that can be used to read the full metadata of the item, or to edit or delete the item using the client that has added it to the record. The put-code is displayed in the response following Location: https://api.sandbox.orcid.org/v2.0/[orcid-id]/employment/[put-code]. In a real-world situation, your system would store this put-code along with the affiliation data in your database.
- Visit the public view of your Sandbox record at https://sandbox.orcid.org/[Your sandbox iD] to see the work that you added in the user interface.
<?xml version="1.0" encoding="UTF-8"?> <education:education xmlns:common="http://www.orcid.org/ns/common" xmlns:education="http://www.orcid.org/ns/education" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.orcid.org/ns/education ../education-2.0.xsd "> <education:department-name>Department</education:department-name> <education:role-title>Degree title</education:role-title> <common:start-date> <common:year>2012</common:year> <common:month>01</common:month> <common:day>01</common:day> </common:start-date> <education:organization> <common:name>My University</common:name> <common:address> <common:city>Some City</common:city> <common:region>Region</common:region> <common:country>US</common:country> </common:address> <common:disambiguated-organization> <common:disambiguated-organization-identifier>XXXXXX</common:disambiguated-organization-identifier> <common:disambiguation-source>RINGGOLD</common:disambiguation-source> </common:disambiguated-organization> </education:organization> </education:education>
In a real-world situation, you may need to update a researcher's affiliation when they finish a degree, change departments, or finish a contract. To update an affiliation, you will require the unique put-code for the affiliation.
- Beneath Step 3: Configure request to API, set HTTP Method to PUT, which is required to update the item.
- At the end of the request URI, add the put-code of the affiliation you just created, e.g. https://api.sandbox.orcid.org/v2.0/0000-0002-3791-8427]/employment/employment/26651. Without the put-code, you cannot update the affiliation.
- Click Enter request body. This is where you’ll enter the XML for the work that you wish to edit.
- Go to [sample-employment-affiliation-edit.xml](sample-employment-affiliation-edit.xml) and copy the XML.
- Paste the XML in the Request Body field and amend to reflect your institution.
Tip: The amended area are lines 1 (edit) and lines 13-11 (new data). You can copy line one and use it to replace the first line of your data; enter the unique put-code in place of "put-code="XXXXX"". The new data begins begins with <common:end-date>, and you can can paste it after the </common:start-date> in the active Request Body.)
- Click Close.
- Click Send the Request.
- The results will appear in the Request/Response section on the right side of the screen. Scroll down – if you see HTTP/1.1 200 OK, the affiliation was successfully posted!
If you receive an error, be sure to check that the headers value under Add headers have not been changed to garbled text, e.g. "application%2Fvnd.orcid%2Bxml".
- Visit the public view of your Sandbox record at https://sandbox.orcid.org/[Your sandbox iD] to see the changes to the work in the user interface.
Organizations are often interested in creating ORCID records on behalf of their faculty, staff, or students. The ORCID API supports this through a create on demand process that allows users to create a new record at any time, and to grant your system read/write access to their record (via the API). Users who already have an ORCID iD can use the same process to send their existing iD to your system and grant your system read/write access.
See a demo of this process at: https://orcid-create-on-demand.herokuapp.com
In this section, we’ll walk through the basic steps to implement a create on demand process. For more information, see http://members.orcid.org/create-records
The create on demand process begins with a special authorization URL that you construct. The URL includes your ORCID API client credentials and information about any read/write permissions that you’d like to request from the user.
Your authorization URL begins with one of the following addresses, depending on the environment that you’re using.
Sandbox API |
|
Production API |
- Open a text editor and copy/paste or type the base URL into a new document. For this tutorial, we’re using the Sandbox API, so our base URL is:
After the base URL, we need to include some additional bits of information – called “parameters” – that identify your client app to the ORCID API and tell the API what permissions you’d like to request from the user. Each parameter is separated by an & character.
| client_id | Your Member API client ID (ex: APP-E422WM33OPZWKKMQ) |
scope |
The read/write permission(s) you wish to request from the user, from the ORCID Scopes list If including multiple permissions, separate them with an HTML-encoded space (%20), ex: /orcid-works/create%20/orcid-works/update At minimum, /authenticate needs to be included, which allows you to obtain the user’s ORCID iD. |
response_type |
code |
redirect_uri |
The page on your site that the user should be sent to when the authorization is complete, ex: http://yoursite/somepage.html |
- In your text editor, add the required parameters to your base URL, as in the example below. Make sure to replace the Client ID with your assigned Client ID!
https://sandbox.orcid.org/oauth/authorize?
client_id=APP-E422WM33OPZWKKMQ&
scope=/orcid-works/create%20/orcid-works/update&
response_type=code&
redirect_uri=https://developers.google.com/oauthplayground
In addition to the required parameters, you can add any of the optional parameters below to customize the ORCID authorization screen and pre-fill the registration form with information from your system.
state |
A random value used as a security tactic to prevent Cross-Site Request Forgery (CSRF). When ORCID sends the user back to your redirect_uri, the state value will be included in the response. |
family_names |
The user's family (last) name, used to pre-fill the registration form. |
given_names |
The user's given (first) name, used to pre-fill the registration form. |
The researcher's email address, used to pre-fill the sign-in or registration form. |
|
lang |
The language to display the authorization page in, as a 2-letter ISO 639-1 code. |
show_login |
Forces the login form to display by default, set to true or false. |
In your text editor, add some optional parameters to pre-fill the registration form. Your final authorization URL should like something like:
https://sandbox.orcid.org/oauth/authorize?
client_id=APP-E422WM33OPZWKKMQ&
scope=/orcid-works/create%20/orcid-works/update&
response_type=code&
redirect_uri=https://developers.google.com/oauthplayground&
family_names=Orcidson&
given_names=Orc&
[email protected]
After clicking your authorization URL and completing the ORCID registration or sign-in process, users are sent to the page that you specified in the redirect_uri parameter.
When a user is sent to this page, the ORCID API attaches an Authorization Code to the end of the URL for the page. As we saw in the previous sections of this tutorial, an Authorization Code can be exchanged for a user’s ORCID iD and (optionally) an Access Token.
In this tutorial, we’ve been relying on the OAuth Playground to perform the authorization code exchange. In a live application, this is done by your system via your specified redirect page.
This step requires some programming expertise, so you may need to enlist the help of a web developer. A variety of languages can be used – code can be executed right in the redirect page, or the redirect page can connect to an application living on your server.
Regardless of the language, your redirect page (or any server application it connects to) needs to:
- Capture the Authorization Code.
- Exchange the Authorization Code for an Access Token.
- Store the Access Token and ORCID iD (e.g. in a database) for use in future use.
See an example in PHP at: https://github.com/lizkrznarich/orcid-demo-app
For more examples contributed by ORCID members, see: http://members.orcid.org/api/code-examples
Note: If you simply want to promote ORCID creation, but don’t need to collect users’ ORCID iDs or Access Tokens, you can create a static HTML redirect page that does not perform an authorization code exchange.
Once you’ve created an authorization URL and a redirect page, the next step is to prompt users to click the authorization URL. To do this, you can:
- Send each user an email with the authorization URL.
URLs can easily be customized with family_name, given_name, and email parameters using the mailmerge feature available in many email programs.
- Create a page on your site with the authorization URL included as a button or a link.
For this tutorial, simply copy the link and paste it into your browser’s address bar and press Return/Enter.
- If you’ve signed out of your Sandbox account since the prior exercises, you should see the ORCID registration form with the name and email address pre-filled – to finish creating your new sandbox account:
- Enter a password (twice).
- Click the checkbox beside I consent to the privacy policy…
- Click Authorize.
- You’ll be sent to the redirect URI (Google OAuth Playground), and you’ll see the 6-character Authorization Code in your browser’s address bar. A confirmation email will also have also been sent to the address that you specified in the registration form.
- Leave the OAuth Playground window open for the next steps, but don’t exchange the Authorization Code yet.
In a live application, this step would be completed via your redirect page, as discussed above. For this tutorial, we’ll continue to use the OAuth Playground.
Before we continue with the Authorization Code exchange, we first need to make sure that the OAuth Playground is still configured correctly.
- Click the gear icon in the upper right corner to open the configuration form.
- In the configuration form, verify that the following settings (which are the same as those used in sections 4.6 and 4.7) remain. Re-enter any that are not set.
- Click Close in the lower left corner of the configuration screen.
- Beneath the Authorization Code field, click Exchange authorization code for tokens.
- The token will appear in the Access Token field and in the Request/Response section on the right side of the screen. The Request/Response section also includes the user’s name and ORCID iD, and the scope(s) for which token is valid. In your live app, these are the pieces of information that your system should store.
OAuth flow |
Server-side |
OAuth endpoints |
Custom |
Authorization endpoint |
|
Token endpoint |
|
Access token location |
Authorization header w/Bearer prefix |
OAuth Client ID |
Your Member API client ID (ex: APP-E422WM33OPZWKKMQ) |
OAuth Client Secret |
Your Member API client secret (ex: ae857cfb-446b-4c3f-8a09-55436bf602dc) |
Once you have the user’s ORCID iD and Access Token, it can be used to make API calls that read from/write to the user’s ORCID record per the permissions requested, as we did earlier in this tutorial.
Access Tokens are valid for 20 years by default. They can be used immediately or at any point in the future.
For example, you can:
- Read information from the user’s ORCID record and copy it into your system.
- Add information from your system to the user’s ORCID record – affiliations, works, etc.
- Update the user’s ORCID record when new information is available in your system.
- Update your system when new information is added to the user’s ORCID record.
- See example implementations and workflow guides http://members.orcid.org
- Read technical documentation http://members.orcid.org/api
- Join the ORCID API Users Group https://groups.google.com/group/orcid-api-users
- Sign up for a Technical Webinar http://members.orcid.org/event-list
- Email ORCID Support [email protected]