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
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:
| Parameter | Field | Notes |
| given_names | First name | The 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_names | Last name | The 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. |
| The 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. | ||
| orcid | ORCID iD | The 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:
| Language | Code |
| (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.
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