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

Connecting Researchers and Research

Sign in/Register
  • 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
        • Sign in / Register
        • 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
  • 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
          • Release Notes
        • Events
          • Events Calendar
          • Webinars
You are here: Home / Documentation / Integration Guide / Customizing the OAuth experience for your researchers

Customizing the OAuth experience for your researchers

When requesting your users to create or connect their ORCID iD to your system, you can save your researchers time and effort by filling in the information that your system already has stored about them, setting their display language, and signing them out of any active sessions to ensure that they have signed into the correct ORCID account.

The ORCID APIs offers several options for customizing the user experience

Contents
1. Pre-fill the registration/Sign-in form
2. Set the display language
3. Default to the sign-in form or the registration form
4. Identify the researcher by a custom ‘state’ parameter
5. Optionally, force sign-out
6. Skipping Authorisation

Pre-fill the registration/Sign-in form

ORCID offers the option for members to pre-fill the OAuth registration/sign-in form as part of an API interaction using the parameters on the https://orcid.org/oauth/authorize URL.

What information can I pre-fill on the authentication screen?

Any or all of the parameters can be used:

ParameterFieldNotes
given_namesFirst nameThe first name field will be filled in on the registration form if a specified email address or ORCID iD does not match that of an active ORCID record. 
family_namesLast nameThe last name field will be filled in on the registration form if the specified email address or ORCID iD does not match that of an active ORCID record. 
emailEmailThe email/ORCID iD field will be filled in on the sign-in form if the specified email address is found in our system and no valid ORCID iD is specified.The email field will be filled in on the registration form if the specified email address is found in our system and no valid ORCID iD is specified.The email address should be URL encoded, including changing “@” to “%40”.If you know the user’s ORCID iD and email address, we suggest only providing the ORCID iD in the orcid parameter.
orcidORCID iDThe email/ORCID iD field will be filled in on the sign-in form if the specified ORCID iD is found in our system.The registration form will otherwise be displayed if the specified ORCID iD is not found in our system.The ORCID iD must be in the 16-digit format of the iD URI.

An example URL with these parameters is

https://sandbox.orcid.org/oauth/authorize?client_id=APP-NPXKK6HFN6TJ4YYI
&response_type=code
&scope=/authenticate
&redirect_uri=https%3A%2F%2Fdevelopers.google.com%2Foauthplayground
&family_names=Finn&given_names=Huckleberry&email=huckle%40mailinator.com

Set the display language

ORCID offers the option to specify the display language of the OAuth registration/sign-in form as part of an API interaction using the “lang” parameter on the https://orcid.org/oauth/authorize URL. This will also set the user’s language display preference.

What display languages does ORCID support?

Users can change their display language on their own at any point. The following language settings are available:

LanguageCode
(Arabic)ar
čeština (Czeck)cs
English en
Español (Spanish)es
Français (French)fr
Italiano (Italian)it
日本語 (Japanese)ja
한국어 (Korean)ko
Português (Portuguese)pt
Русский (Russian)ru
简体中文 (simplified Chinese)zh_CN
繁體中文 (traditional Chinese)zh_TW

Example

This example pre-fills the form and sets the language to Spanish

https://sandbox.orcid.org/oauth/authorize?client_id=APP-NPXKK6HFN6TJ4YYI
&response_type=code
&scope=/authenticate
&redirect_uri=https%3A%2F%2Fdevelopers.google.com%2Foauthplayground
&family_names=Finn&given_names=Huckleberry&email=huck%40mailinator.com
&lang=es 

Default to the sign-in form or the registration form

Currently the ORCID OAuth screen presents the sign-in form by default and provides a link to switch to the registration form. Regardless of the default behavior, the form displayed can be set by adding the parameter “&show_login=true” to display the sign-in form or “&show_login=false” to display the registration form. Note that if an email address or ORCID iD are supplied in the URL, the form shown will be determined by those parameters and the &show_login parameter will be ignored. 

ORCID strongly recommends the best practice of allowing end-users to resize the OAuth sign-in window in order to improve accessibility, in line with our values around inclusion. 

Identify the researcher by a custom ‘state’ parameter

This is used by some integrations for technical reasons. It does not appear on the sign in screen.

A state parameter can be included with the authorize URL in order to identify the user, such as a unique sequence of numbers that translates to the user’s internal identifier within your system. The parameter does not affect the user’s experience, but it will be returned with the authorization code and can be used to identify the user or session. The state parameter is also returned if the user denies access.

Optionally, force sign-out

You can log the user out if you are concerned they are multiple users on a single machine.

How do I force a user to logout?

If you are concerned with multiple users being on the same machine and not signing out between sessions, you can force a sign-out before starting the OAuth process. To force a sign-out, send the user to the page https://orcid.org/userStatus.json?logUserOut=true.

An optional callback param can be included with the url to trigger a javascript function you specify, such as sending the user to a redirect. For example: https://orcid.org/userStatus.json?logUserOut=true&callback=%22exampleCallBack%22

We suggest hitting that page as part of a script on the page where user starts the OAuth process. A working example of this is at https://orcid.github.io/test/log-user-out-jsonp.html. View the page source or the project in Github to see how the sign-out is called as a script on that page.

The user is also signed out of their ORCID account if they visit the sign-out page at https://orcid.org/signout.

Skipping Authorisation

ORCID skips authorization in certain circumstances.

When is authorization skipped?

If an active access token already exists with the same scopes that your OAuth authorization URL requests, and the user is signed into their ORCID record, they will not be prompted to grant authorization again. Instead they will be taken directly to the redirect URI. If you want to require a user to grant authorization every time they connect, use the force sign-out method

Primary Sidebar

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
    • 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
  • 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

Github Documentation

Documentation MenuDocumentation Menu
  • API Tech Docs
  • Tech Tutorials
  • Content Negotiation
  • Open ID Connect
  • V3.0 API Schemas
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
ORCID uses cookies to improve your experience and to help us understand how you use our websites. Learn more about how we use cookies. Dismiss