• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar

Connecting Researchers and Research

Sign in/Register
Privacy & Cookies: This site uses cookies. By continuing to use this website, you agree to their use.
To find out more, including how to control cookies, see here: Privacy Policy
  • About
        • Our Mission
          • 2025 Vision
          • ORCID Trust
          • Annual Reports
        • Team
          • ORCID Board
          • ORCID Team
          • Work with Us!
        • Services
          • Member Portal
          • Annual data files
          • Member API
          • Public API
          • ORCID Registry
        • Governance
          • Bylaws
          • Board Elections
        • Policies
          • Privacy Policy
          • Dispute Procedures
          • Public Client Terms of Service
          • Open Source Project License
          • Public Data File Use Policy
          • Terms of Use
          • Brand Guidelines
  • For Researchers
        • Benefits for Researchers
        • Researcher FAQ
        • Video Tutorials
        • Your ORCID Record
        • Get Help
  • Membership
        • Membership Benefits
          • Benefits for Funders
          • Benefits for Publishers
          • Benefits for Research Organizations
          • Benefits for Research Resources
        • Get Membership
        • Member List
        • ORCID Map
        • Membership Comparison
          • Basic Membership
          • Premium Membership
          • ORCID Consortia
        • ORCID Consortia
          • Consortia Agreement
          • Consortia Onboarding Checklist
          • Roles and Responsibilities of ORCID Consortia
  • Documentation
        • Features
          • Member Portal
          • Member API
          • Public API
          • ORCID Registry
          • Annual Data Files
        • Workflows
          • Journal Articles
          • Employment
          • Peer Review
          • Funder and Grants
          • View More
        • Integration Guide
          • Getting Started with Your Integration
          • Sandbox Testing Server
          • Registering a Member API Client
          • Integration and API FAQ
          • View More
        • API Tutorials
          • Get an Authenticated ORCID iD
          • Read Data on a Record
          • Add and Update Data on an ORCID record
          • Hands On with the ORCID API
          • View More
        • Member Portal
          • Member Portal Organization Admin Guide
          • Member Portal Email Guide
          • Member Portal Beta Program Guide
  • Resources
        • ORCID Community
        • Community Programs
          • Certified Service Providers
          • ORCID API Users Group
          • Historical Task Forces, Working Groups, and Steering Groups
        • Get Involved
          • Community Groups
          • Developers
          • Give Feedback
          • ORCID API Users Group
        • Member Resources
          • ORCID Enabled Systems
          • Publishers Open Letter
          • Funders Open Letter
          • Standard Member Agreement
          • Outreach Resources
          • Register a Sandbox API Client
          • Register a Production API Client
  • News & Events
        • News
          • ORCID News
          • Member News
          • Consortia News
          • Integration News
          • Blog
          • Product Updates
        • Events
          • Events Calendar
          • Webinars
You are here: Home / Documentation / API Tutorials / API Tutorial: Get an Authenticated ORCID iD

API Tutorial: Get an Authenticated ORCID iD

The tutorial describes the steps to authenticate an ORCID iD. It can be completed using either the public or member API. It reviews the steps to retrieve a verified ORCID iD, which can then be stored in your system’s database. There are two options: 3 legged OAuth (for long lived update permissions) and Implicit OAuth (for read-only short term permissions).

Contents
1. Get some client credentials
2. Register your redirect URLs
3. Implement OAuth

Get some client credentials

Client credentials are the username and password your application/website will use to access the ORCID API. Anyone can register for read-only Public API credentials, ORCID members can register for the member API.

How do I register a Public API client?

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!

How do I register a test client on the Sandbox Member 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. 

Register your redirect URLs

Once signed in, users are sent to a URL you specify as part of registering a client.

How do redirect URIs work?

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.

Implement OAuth

Below we explain the three ‘flavours’ of OAuth supported by ORCID. Most programming languages have OAuth and/or OpenID libraries available that make integration easier.

3-legged OAuth

This is the standard way of authenticating a user’s ORCID iD and can be used to obtain long lived update permissions alongside the authenticated ORCID iD.

How does “3 legged OAuth” work?

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

This is the browser-centric way of authenticating a user’s ORCID iD for use by browser based applications that do not require update permissions.

How does implicit OAuth work?

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

OpenID is built on top of OAuth and offers some additional features.

What is OpenID?

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.


Primary Sidebar

Search

Documentation

Documentation MenuDocumentation Menu
  • Features
    • Public API
      • Sign in option to your system
      • Collecting authenticated iDs
      • Reading ORCID records
      • Searching the registry
    • Member API
      • Access trusted data
      • Writing data to ORCID records
      • Syncing ORCID with your system
    • Member Portal
      • Member Portal Organization Admin Guide
      • Member Portal Email Guide
      • Member Portal Beta Program Guide
    • ORCID Registry
    • Annual Data Files
  • Workflows
    • Journal Articles
    • Books
    • Preprint Servers
    • Peer Review
    • Education
    • Employment
    • Invited Positions and Distinction
    • Membership and Service
    • Research Resources
    • Funder and Grants
    • Repository Systems
    • eTheses and Dissertation
    • Institutional Connect
    • Search and Link Wizards
    • Sharing User Permissions
    • Connecting with Co-Authors
    • Accreditations and qualifications
  • Integration Guide
    • Getting Started with Your Integration
    • Sandbox Testing Server
    • Registering a Public API Client
    • Registering a Member API Client
    • ORCID and Persistent Identifiers
    • Working with Organization Identifiers
    • Sign into ORCID with Institutional Credentials
    • Sign In Using ORCID Credentials
    • Syncronizing with ORCID
    • Working with Bulk Data
    • ORCID Record Schema
    • Troubleshooting
    • User experience display guidelines
    • Customizing the OAuth Experience
    • Vendor Systems
    • Communicating with Users
    • Integration and API FAQ
  • API Tutorials
    • Getting an Authenticated ORCID iD
    • Reading Data on a Record
    • Adding and Updating Data
    • Searching the ORCID Registry
    • Registering a Notification Webhook
    • Hands on with the ORCID API
  • API Technical Resources
    • Tech Tutorials
    • 3.0 Schemas
    • API Error Codes
    • Maven Central
    • ORCID OAuth Java Script Widget
ORCID logo

CC0 The text of this website is published under a CC0 license Images and marks are subject to copyright and trademark protection.

  • About ORCID
  • Privacy Policy
  • Terms of Use
  • Accessibility Statement
  • Contact us
  • Dispute procedures
  • Brand Guidelines