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.
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.
The ORCID APIs offers several options for customizing the user experience
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.
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 |
| Deutsch (German) | de |
| Italiano (Italian) | it |
| 日本語 (Japanese) | ja |
| 한국어 (Korean) | ko |
| Polski (Polish) | pl |
| Português (Portuguese) | pt |
| Русский (Russian) | ru |
| Türkçe (Turkish) | tr |
| 简体中文 (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.
Identify the researcher by a custom ‘state’ parameter
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. Please note that the state parameter has a 2000 character limit.
Optionally, force sign-out
You can log the user out if you are concerned there are multiple users on a single machine.
If you are concerned with multiple users being on the same machine and not signing out between sessions, you can force them to re-authenticate during the OAuth process. Simply include prompt=login in the OAuth request.
Skipping Authorization
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