1.2 Tutorial: Retrieve an ORCID iD (archive)

This guide is an archived document related to the 1.2 version of the ORCID Message Schema, which is no longer supported by ORCID. The current supported version is 2.0 documentation. Go to the document for the 2.0 Message Schema.

Introduction

This tutorial will go over the steps to retrieve a verified ORCID iD, which can then be stored in another database.  In this process, the user will sign into the ORCID registry and authorize access their ORCID iD. The tutorial uses cURL statements, when trying the examples the text in bold should be replaced with your own credentials and system responses.

Scope & Authorization

The /authenticate scope used in this tutorial can be used with the member API or the public API. The API in use determines the base URL for making call to the API.

  • Public API: https://pub.orcid.org/
  • Public API Sandbox: https://pub.sandbox.orcid.org/
  • Member API: https://api.orcid.org/
  • Member API Sandbox: https://api.sandbox.orcid.org/

The examples in this tutorial us the member sandbox API, to use another API just edit the base URL to one listed above.

The process for retrieving an ORCID iD follows the OAuth dance as described in Tokens Through 3-legged OAuth Authorization.

GET the ORCID iD

The process to get an ORCID iD has a user start from your local system where they are then directed to an ORCID URL with your client id, the authenticate scope, and your redirect URI. At the ORCID site the researcher will need to sign in and simultaneously authorize your system to confirm who they are. Upon signing in and clicking "authorize", the researcher will be returned to the redirect URI provided, and this URI will be appended with an authorization code. This authorization code should be stored by your system, and then exchanged for the researcher's ORCID iD.

An example call to obtain the authorization code to get the ORCID iD of a sandbox account is below. 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. To obtain the code, sign into an existing ORCID account on the sandbox (or create a new sandbox account); you will then be returned to the specified redirect URI, which will have a 6-character authorization code appended to the end of that URL.

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

With this example, the final URL with the authorization code will resemble the following: 

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

You can then immediately exchange the authorization code for an access token and the ORCID iD. (This exchange should occur within 10 minutes at least. The auth code will expire within 24 hours.) An example cURL statement and response is below

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"

response

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-0003-1495-7122","name":"ORCID Test "}

The ORCID iD can then be recorded in your system.

For troubleshooting errors in this process please see API Error Codes.