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 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 a third-party system that already supports ORCID, you may not need to register for sandbox API credentials. 

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 ORCD 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.

The sandbox server sends notification emails only 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. 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 a free 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 and 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 or search for ORCID records. 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. If you are not a premium member, but wish to test this function in the Developer’s Sandbox, please contact ORCID Community.

• In the past ORCID supported other scopes, that have now been phased out.
• You can find out which scopes are required to add or update a particular sections here.

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 update. Store it together with the researcher’s information. 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. Persistent tokens are valid for approximately 20 years or until the user revokes them. Refresh tokens can be used to create new access tokens with the same or limited scopes. Store the tokens together with the researcher’s information.  We also recommend you store the token scope, and the token expiry.
• Accept and store put codes (if updating ORCID records): Every item that you add to the ORCID Registry will be returned with a put code by the ORCID API. Save this put code along with the item in your system—it’s how you’ll identify which item needs to be read or updated.
• Log interactions: Your system should record both calls made to the ORCID API and responses received. This is necessary so ORCID can help if a problem develops later.
• Provide error messages and a support contact when an interaction does not go as expected.

To ensure that you build the best possible integration for your institution, your researchers, and the wider community, we recommend that you consider the following best practices:

• Customize the user experience: Use data your system has stored to pre-fill the OAuth sign in/registration screen. You can also include state parameters to identify the user in your system or change the display language on ORCID.
• Provide a workflow for users if they deny your system permission: Provide a message to users which clearly explains what ORCID is, why your system is requesting permission to their ORCID record, and what you will do with that permission, and offer the option to again grant permission.
• Provide an option for users to remove their ORCID iD and data from your system: In rare cases, a user may wish to remove their iD from your system, or they may have connected the wrong ORCID iD. Ensure that any active access tokens are also revoked by your system at the same time.
• Update added items when corrections are needed using the item’s unique put code.
• Provide descriptive error messages and a support contact to your users when an interaction does not go as expected.
• Display the ORCID member logo (contact us to receive it) 
• Create a consistent user experience by associating the iD icon with a trusted assertion process. Our ORCID Brand Guidelines for Members and Partners will take you through the process for setting up the display of the iD icon in your system, as well as outline do’s and don’ts of displaying the ORCID brand.
• Use the access token to check for existing permissions: Once you have received permissions from the user once, you should not need to request them again.

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.

There are a number of requirements that we expect all member integrations to meet. The ORCID team will ensure these requirements have been met as part of the integration review process. 

• Use OAuth to authenticate ORCID iDs (Do not allow users search for or type in ORCID iDs.)
• Include an ORCID branded button or link on your site to initiate authentication of the iD.
• Present the OAuth authorization screen according to our guidelines
• Use HTTPS for your site’s redirect URIs and on ORCID API calls
• Accept and store all data returned in the token exchange together with the user’s data in your system
  • ORCID iD: Your system will need to know the user’s iD to read or update their record.
  • Access tokens and refresh tokens to:
    • Indicate that the ORCID iD has been authenticated
    • Use to read or update the ORCID record at a later point (access tokens are valid for 20 years or until you or the user revokes them)
    • Reissue access tokens if lost, or issue secondary access tokens for a limited scope or duration to third parties, e.g. service providers
  • Permission scope: So you will know the permissions you have requested and received from the user, or the scope of any secondary tokens.
  • Expiry: To know the duration of the permissions of the token.
• Use appropriate scopes and request methods (e.g. POST calls to add new information and PUT calls to update existing information)
• Accept and store put codes (if adding data to ORCID records): Every item that you add to the ORCID Registry will be returned with a put code by the ORCID API. Save this put code along with the item in your system—it’s how you’ll identify which item needs to be read or updated.
• Publicly display the authenticated ORCID iDs: Authenticated ORCID iDs should be displayed within your systems where the individual’s name is present, both in visual representation as well as in metadata. iDs should be displayed following our trademark and iD display guidelines.
• Provide an explanation about ORCID: Ensure your researchers know about ORCID and how you are integrating with us by providing an explanation clearly linked from wherever the user will be encountering ORCID in your system, including an explanation of your integration

Best practices

Make sure your integration follows best practices

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

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. This also gives us an opportunity to learn more about how your system works, and how you’re explaining the benefits of your ORCID integration, so we can provide better support for you and your users.
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 (recommended for ORCID-enabled systems which require a demonstration): 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. 

If you are using one of the ORCID-enabled systems that does not require a demonstration, you can directly request production Member API credentials. Be sure to specify which system (and, if applicable, version) you’re using in the notes.

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

Notes for ORCID staff: Use this field to let ORCID know if you’re using a vendor system, integrations been reviewed etc.

Contact email address: We will send the credentials to this address. This should be the contact that we have been working with on the integration or the technical contact that we hold for your organisation.

Contact for receiving PIN to access credentials: We send the full credentials to you in a secure way. We will send a passcode to access your API credentials to this contact. This needs to be a different contact to the previous contact listed.

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

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

OAuth2 redirect URIs or callback URLs for the client: Permitted URL(s) in your web application where users will be returned to after they authorize access to their ORCID record data. All redirect URIs must be HTTPS for production (live) server clients. 

Once you have made your request, a manual process happens to issue you credentials and you will get an email with your client iD and client secret. Typically these requests are process in less than 48 hours.