Member API credentials check list

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 Community 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 OAuth and ORCID best practices. We'll also note which elements of Collect & Connect your application meets and award badges accordingly!

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, and to highlight how your integration meets the individual elements of Collect & Connect

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, and follow up with screenshots or links which demonstrate how your integration meets non-technical requirements of Collect & Connect, such as:

  • Explaining to users what ORCID is, either in the system or clearly linked from wherever the user encounters ORCID in your system
  • Explaining how your system works with ORCID, Including:
    • How you authenticate ORCID iDs and why this is important for you and the research
    • Where you display iDs and why
    • If applicable: How you connect your information to the researcher’s ORCID record and how this benefits you and the researcher
    • If applicable: How you collect information from the researcher’s record and how this benefits you and the researcher.

Please send your screenshots to the ORCID Community Team.

 

Requirements for ORCID integrations

Collect & Connect 

We strongly encourage all ORCID integrations to follow the best practices provided in our Collect & Connect program; meeting two or more these requirements is an important part of your integration review. All ORCID member integrations must meet the requirements for Authenticate and Display. Connect, Collect, and Synchronize are optional, but we highly recommend planning for your integration to meet these requirements in the longer term, if not right away. Your integration will receive a badge for each element it fulfils which can be displayed within your system.

Version

Use the latest ORCID message schema, or a supported release candidate version. Currently integrations must be using version 2.0 or higher.

Mandatory Requirements

  • Use OAuth to authenticate ORCID iDs and follow the OAuth 2.0 specifications. (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

Additional requirements for service providers

If you are a service provider, you also need to provide the member the ability to:

  • Export stored ORCID iDs and token exchange data in association with user information
  • Export put codes and data (if the system also writes data)

Best practices

  • For service providers - credentials configuration: Provide the option for members or public API users to input and edit their API credentials within your system
  • 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.
  • Sign users out of ORCID before they connect their iDs: To help ensure that no iDs are incorrectly linked which can sometime happen if using a shared computer.
  • 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.
  • 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. You can also check the validity of the access token each time the user signs into your system, and request that they refresh permissions if it has expired.
  • Update added items when corrections are needed using the item’s unique put code.
  • Log interactions: Your system should record both calls or requests made to the ORCID API and responses received. This is necessary so ORCID can help if a problem develops later.
  • Provide descriptive error messages and a support contact to your users when an interaction does not go as expected.
  • Logos and Badges: Display the ORCID member logo (contact us to receive it) and Collect & Connect badges that your integration has been awarded.