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

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.
email	Email	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.

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 there are multiple users on a single machine.

Skipping Authorisation

ORCID skips authorization in certain circumstances.