• 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

How does “3 legged OAuth” work?

January 14, 2020 By Tom Demeranville

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.

Was this helpful?

 

Additional Comments:


Primary Sidebar

Search

Blog Posts by Category

  • Consortia News (39)
  • Integration News (50)
  • Member News (30)
  • News (434)
  • ORCID News (196)
  • Product Updates (75)

Recent Posts

  • Restructuring Engagement to Optimize Member Support
  • OpenAIRE EXPLORE Makes it Simple to Add Works to Your ORCID Record
  • 2021 Product: Our Progress to Date and Future Plans
  • Use Your ORCID Record to Build Your Career: An Interview with Dr. Adriana Romero-Olivares
  • ORCID and Morressier

Sign up for blog updates

We will only use your email to notify you when we have new blog posts. You can unsubscribe at any time. See our Privacy Policy for more information.

Check your inbox or spam folder to confirm your subscription.

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