The ORCID Member API uses OAuth 2.0 to manage its authentication. This document describes how to use Google Developers’ OAuth 2.0 Playground to explore OAuth for the ORCID environment.

1. Using OAuth 2.0 Playground
How to set up OAuth 2.0 Playground to work with the ORCID’s OAuth and APIs
Table of Contents
Introduction 1
About Google Developers OAuth 2.0 Playground 1
STEP A: Create an API Client App for the Developers’ Sandbox 1
STEP B: Set up the Playground 2
OAuth 2.0 configuration 2
STEP C: Use the Playground 3
Step 1 – Select & authorize APIs 3
Step 2 – Exchange authorization codes for tokens 3
Step 3 – Configure request to API 4
Introduction
The ORCID Member API uses OAuth 2.0 to manage its authentication. This document
describes how to use Google Developers’ OAuth 2.0 Playground to explore OAuth for
the ORCID environment.
About Google Developers OAuth 2.0 Playground
ORCID does not maintain or develop for the OAuth 2.0 Playground. This tool was
created by Google who exclusively maintains its code. While we will try to maintain this
documentation so that it is up-to-date, changes in Google’s platform could make these
instructions in accurate from time-to-time. Your contributions will help us to maintain
this document.
STEP A: Create an API Client App for the Developers’
Sandbox
Before you can make any request you need to create an API client that will give you a
consumer KEY, and SECRET. If you’ve ever used an API before you can think of the
client as your API KEY. It is required to help identify your application which may be a
web-application, a server-side script that does some backend integration or a piece of
Javascript that pulls information from the Registry.
Please see our knowledge base for more information on this step:
http://orcid.uservoice.com/knowledgebase/articles/116739-register-a-client-application
Now that you have a client, you can move onto making some actual requests!
1

2. Understanding the ORCID OAuth Dance
STEP B: Set up the Playground
The first thing you will need to do is set up the playground to work with the ORCID
environment. Go to the OAuth 2.0 Playground URL, and click the gear to configure it:
https://developers.googlecom/oauthplayground/
OAuth 2.0 configuration
OAuth flow: Server-side
OAuth endpoints: custom
Authorization endpoint: http://devsandbox.orcid.org/oauth/authorize
Token endpoint: http://api.devsandbox.orcid.org/oauth/token
Access token location: Authorization header w/Bearer prefix
OAuth Client ID: (from your client registration - <client-id>)
OAuth Client secret: (from your client registration - <client-secret>))
A Shortcut: The following URL has been configured as described above – you
will only need to enter your Client ID and secret:
https://developers.google.com/oauthplayground/#step3&url=http%3A//api.devsand
box.orcid.org/&content_type=application/json&http_method=GET&useDefaultOa
uthCred=unchecked&oauthEndpointSelect=Custom&oauthAuthEndpointValue=htt
2

3. Understanding the ORCID OAuth Dance
p%3A//devsandbox.orcid.org/oauth/authorize&oauthTokenEndpointValue=http%3
A//api.devsandbox.orcid.org/oauth/token&includeCredentials=unchecked&accessT
okenType=bearer&autoRefreshToken=unchecked&accessType=offline&forceApro
valPrompt=checked&response_type=code
STEP C: Use the Playground
OBTAIN A TOKEN: You are going to
be using the Playground to obtain a
token as described in the knowledge
base article Tokens Through 3-legged
OAuth Authentication
(http://orcid.uservoice.com/
knowledgebase/articles/119676-
tokens-through-3-legged-oauth-
authorization)
USE THE APIs: Once you have a
token, you will use it to perform API
calls as described in the ORCID API
Guide
(http://orcid.uservoice.com/
knowledgebase/articles/116874-orcid-
api-guide).
Step 1 – Select & authorize APIs
Enter a scope from one described in the knowledge base at:
(http://orcid.uservoice.com/knowledgebase/articles/120162-orcid-scopes).
When you click the Authorize APIs, the user will be requested to log in (or create a
new ORCID ID), and then authorize the scope that you have created. For this step, you
will find it handy to have (or create
during this process) an account on the
Developers Sandbox that you will be
using as your “researcher” who is
“authorizing the scopes”.
Step 2 – Exchange
authorization codes for tokens
Once the end user (most likely
represented by you logging in in this
example) has authorized a specific
scope, you will receive an authorization
code which you will see displayed in
step two. Click “Exchange authorization
3

4. Understanding the ORCID OAuth Dance
code for tokens”. This action will create an access token that you will see in the
“Request/Response” window to the right of the screen.
The Response:
Note the “access_token” that was provided via OAuth – you will be using this token to
configure your request to the API.
Step 3 – Configure request to API
Next you are going to configure and send your request to the API
NOTE: The screen shot above was taken from a different server. Your request URI should be
http://api.devsandbox.orcid.org/[REQUEST].
Since the requested scope limits what you will be able to see, you always will be able to use the
following URI in the Developers Sandbox: http://api.devsandbox.orcid.org/[ORCID_ID]
You will set the HTTP Method, Request URI and Headers as described in the ORCID
API Guide (http://orcid.uservoice.com/knowledgebase/articles/116874-orcid-api-guide).
4

5. Understanding the ORCID OAuth Dance
A special note about the Authorize Header
You will need to add an “authorize” header that will contain your access code preceded
by the term “bearer”
A special note about the Accept Header
You can format the result to be HTML, XML or JSON by setting an “accept” header and
setting the value to one of those shown below.
Format Accept Header Description
HTML text/html Redirects to the ORCID web user
interface to display the result
XML application/orcid+xml OR XML conforming to the orcid-
application/xml message.xsd
JSON application/orcid+json OR JavaScript Object Notation equivalent to
application/json the orcid-message.xsd
The Response
In the Request / Response window you will see the resulting content based on the API
call. For example:
GET /0000-0002-9652-3185 HTTP/1.1 Host: api.orcid.orc.test.semantico.net Authorize: bearer 5e1b56ed-
3388-435a-95e3-08d6e94f73fa Content-length: 0 Authorization: Bearer f8db2f09-d862-4318-84bc-
a2ed1cd89648
HTTP/1.1 200 OK Content-length: 1382 Via: HTTP/1.1 GWA Content-location:
http://api.orcid.orc.test.semantico.net/0000-0002-9652-3185 X-google-cache-control: remote-fetch Server:
Apache-Coyote/1.1 Date: Wed, 05 Sep 2012 00:26:31 GMT Content-type: text/html;charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<orcid-message xmlns="http://www.orcid.org/ns/orcid">
<message-version>1.0.3</message-version>
<orcid-profile type="user">
<orcid>0000-0002-9652-3185</orcid>
<orcid-history>
5

6. Understanding the ORCID OAuth Dance
<creation-method>website</creation-method>
<completion-date>2012-08-17T18:41:48.816+01:00</completion-date>
<submission-date>2012-08-17T18:41:44.703+01:00</submission-date>
<claimed>true</claimed>
</orcid-history>
<orcid-bio>
<personal-details>
<given-names>Laura</given-names>
<family-name>Paglione</family-name>
<credit-name visibility="public">Laura AD Paglione</credit-name>
<other-names visibility="public"/>
</personal-details>
<biography visibility="public"></biography>
<external-identifiers visibility="public"/>
<affiliations>
<affiliation visibility="public">
<affiliation-name>ORCID</affiliation-name>
<affiliation-type>current-primary-institution</affiliation-type>
<role-title>Administrator</role-title>
</affiliation>
</affiliations>
</orcid-bio>
<orcid-activities/>
</orcid-profile>
</orcid-message>
Document Revision History
Ver Date Who Description
2.0 28 Sep Laura Paglione Refreshed document to reference articles in the
2012 new Knowledge Base.
1.2 11 Sep Laura Paglione Fixed the provided “quick start” URL for the
2012 Playground. Corrected a typo introduced in
version 1.1.
1.1 10 Sep Laura Paglione Updated the URLs in step B for the Token and
2012 authorize endpoints. Thanks to William Penney!
1.0 6 Sep 2012 Laura Paglione Updated to include the limitation of the OAuth
Playground to accommodate new registrations
during the Authorize process.
0.5 4 Sep 2012 Laura Paglione Initial Draft
6