Getting started with your integration

You can request sandbox Member API credentials to build and test your application. These credentials allow you to make calls to the sandbox premium member API to read, write to, and update ORCID records. Access to the sandbox testing environment is freely available to anyone, even if you’re not an ORCID member organization.

Note: If you are using an ORCID certified service provider systemthat already supports ORCID, you do not need to register for sandbox API credentials unless you wish to try out the ORCID integration functionality within the Sandbox envrionment. 

The sandbox lets you create test user accounts and develop your integration without having to worry about affecting data on the live (production) ORCID Registry. The sandbox behaves the same way as the production ORCID Registry with a few exceptions.

Creating a test account

In order to test the ORCID API and API calls, such as a reading and adding information to an ORCID record, you will also need to create a test ORCID record in the sandbox. This can be done through the user interface, much like on the production ORCID Registry. Go to https://sandbox.orcid.org/register and register for an account.

Mailinator email addresses

The sandbox server only sends emails to Mailinator (@mailinator.com) email addresses in order to not spam mail servers unintentionally. You will not receive a verification email or password reset notification unless you use a @mailinator.com address, and verification is required in order to make any manual edits to sandbox records. Find out more about their free to use public inboxes here. If you do not wish to use a Mailinator address, then please make note of your username and password (as you will be using them to grant authorization to your application when testing), and contact us to request assistance with verification.

Mailinator is an email service that has a public free service and a private paid service. For testing you can use the completely free public service. Find out more about their tiers here.

Mailinator is a third party service that is not managed or maintained by ORCID. We recommend that you review how this service works and its limitations before using these addresses.

When requesting permission to interact with an ORCID user’s record, you specify one or more ‘scopes’. Each scope allows you to do certain things, such as read the record, or update a particular section.

3-legged (authorization code) scopes

3 legged refers to the three actors involved in obtaining permission from a user; ORCID, your system and the user themselves.

/authenticate

This scope is used to collect the ORCID iD and read public information on the record only. All other 3-legged scopes include the authenticate permission, so this scope can be omitted if asking for any other access. This scope is available on the Member or Public API.

/read-limited (Member API only)

This scope is used to get access to read public and limited visibility items on an ORCID record. This scope is only available on the Member API.

/activities/update (Member API only)

This scope is used to write, update and delete items in the affiliation, funding, works, professional activities, research resources and peer-review sections of an ORCID record. This scope is only available on the Member API.

/person/update (Member API only)

This scope is used to write, update and delete items in the other-names, keywords, countries, researcher-urls, websites, and personal external identifiers sections of the record. This scope is only available on the Member API.

openid

This scope is used by OpenID integrators when an id_token is required. When the openid scope is included, the Registry will return an id_token inside the token response and grant the client permission to access the user info endpoint for that user. This scope is available on the public and member API.

Please note that the ‘openid’ scope does not start with a ‘/’ like the other ORCID API scopes. This is because the ‘openid’ scope is not defined by ORCID, but instead defined by the OpenID Connect specification. Please see our OpenID documentation for more information.

Multiple scopes

Multiple scopes can be requested in a single interaction by listing the scopes in the authenticate URL with an encoded space between each, such as scope=/read-limited%20/activities/update%20/person/update

Complete access

If you want full access to read and edit a record include three scopes in your authenticate URL: /read-limited, /activities/update and /person/update. In the URL they would appear as scope=/read-limited%20/activities/update%20/person/update

2-legged (client credential) scopes

For some activities you do not have to ask the user for permission. Two legged OAuth scopes are requested directly from the ORCID API and do not require the researcher to grant permission. Tokens with these scopes are valid for 20 years and can be reused

/read-public

This scope is used to read public information on a single ORCID iD,search for ORCID records or to read summary information (member API only). This scope is available on the Member or Public API.

/webhook

This scope allows a client application to register a webhook on an ORCID record, in order to receive notifications when a record is updated. This scope is available to premium ORCID members only.

Integrations need to store more than just ORCID records. Your system will need to be able to:

• Accept and store ORCID iDs: Your system will need to know the iD of the ORCID record to display the iD and to update correctly. Store it together with the researcher’s information which is returned in the token exchange response. Our recommendation is to store the full https URI: https://orcid.org/0000-0001-5727-2427.
• Accept and store persistent access tokens and refresh tokens: Access tokens can be used to read and update records, as well as indicate that the iD has been authenticated. Access tokens are valid for approximately 20 years or until the user revokes them. We also recommend you store the token scope, token expiry and refresh tokens. Refresh tokens can be used to create new access tokens with the same or limited scopes if required. Store the access token token data together with the researcher’s information.
• Accept and store put codes : Every item that you add to the ORCID Registry will be returned with a put code by the ORCID API. Save this 6 digit put code along with the item in your system‚ it’s how you will identify which item needs to be read, updated or deleted.
• Provide error messages and a support contact when an interaction does not go as expected.

Member organizations request ORCID Member API credentials on the production (live) server by completing the Production Member API client application form. Before issuing production Member API credentials, the ORCID Engagement team/Consortia Lead will review a demo of your integration in the ORCID sandbox. This gives us a chance to see the great integrations you have built and offer workflow improvements, as well as check that all integrations meet our best practices and minimal requirements for launch.

To provide a demo of your system you’ll need to set up a working integration with the ORCID sandbox that the ORCID team can preview. There are a few ways to share your working sandbox integration:

1. Recommended: Live demo: Contact us to schedule a live demonstration. We’ll provide meeting software that allows you to share your screen for you to demo your integration. 
2. Test site: If your development site is public, send us the URL along with test credentials (if needed) to access your system and instructions describing how to use your system’s ORCID features. Provide additional documentation to verify what we would not be able to see from the user end, e.g. API version used, what data is stored by your system, etc.
3. Screencast or screenshots :Send a recording or a set of screenshots with descriptions clearly explaining and demonstrating how your integration works at each step, including what happens if a user denies access or disconnects their iD. Be sure to provide additional documentation to verify anything we would not be able to see from the user end, such as API version used and how data is stored

Member organizations request ORCID Member API credentials on the production (live) server by completing the Production Member API client application form. If you are using a vendor system that is not on the list of ORCID Certified Service Providers, your integration will need to undergo a review process to guarantee that the minimum requirements for integration and best practices are met. 

You can contact your non-certified Service Provider and obtain evidence directly from them that the minimum criteria are met. You will need to send this evidence to the ORCID Engagement team or your Consortia Lead.

There are a few ways to share this evidence:

1. Screencast or screenshots: Send a recording or a set of screenshots with descriptions clearly explaining and demonstrating how your integration works at each step, including what happens if a user denies access or disconnects their iD. Be sure to provide additional documentation to verify anything we would not be able to see from the user end, such as API version used and how data is stored.
2. Publicly available integration documentation: Submit a publicly accessible and up-to-date link that includes a clear description of how the integration works at each step. As in option 1, be sure to provide additional documentation to verify anything we would not be able to see from the user end, such as API version used and how data is stored.

You will need to fill in the form to register a client application. Below is a quick overview of the requested fields:

Name of organization: Your ORCID member organization name

Primary contact email address for credentials: We will use this email address to send you the credentials in an encrypted email, and to contact you if any questions or errors come up with your integration

Secondary email for password: An email address that we can send your encrypted email password to.

Name of your client: This will be your ORCID member organization name. If you have more than 1 integration then we will append the application to the name.

URL of the homepage of your application: Displayed as a link on the list of trusted organizations within the users ORCID trusted parties page. This should be a link back to your organization or the main page of your application.

Short description of your client application: This text will be displayed on the authorization screen with the question mark icon to your integration users. A short description of your integration is required

Redirect URIs: Once the user has authorized your application, they will be returned to a URI that you specify. You must provide these URIs in advance or your integration users will experience an error. 

• Only HTTPS URIs are accepted.
• Domains registered must exactly match the domains used, including subdomains.   
• Register all redirect URIs fully where possible. 
• More than 5 redirect URIs required? Please indicate this in the Notes for ORCID staff.

Notes for ORCID staff: Use this field to let ORCID staff know anything additional about your request or your integration

To support the social component we offer a toolkit of Outreach Resources to help you develop a campaign to support your integration, and communicate to your researchers:

• What ORCID is.
• Why your system collects iDs and how your system will perform tasks, such as updating their records.
• Why your researchers will benefit by creating an ORCID iD and connecting their iDs to your system.
• How ORCID benefits the wider, global research community.

We will be continually building out this “library” of resources based on feedback from the community. If you have an idea for something you might like to see, please feel free to contact us.