- "text": "In our first few API requests, we already knew which ORCID iD to use (our own!) and we read/searched public information, which didn't require any permission from the user. In practice, you'll need to gather up iDs for researchers whose ORCID records you want to read, update, or associate with records in your own system AND get permission to take certain actions, like adding information to their ORCID records. In this section, we'll look at a few ways to get authenticated iDs and/or record access permission.\n\n\nAuthenticated iDs\n\n\nORCID is about disambiguation, it's important that you get the correct iD for each researcher. The best way to do this is to collect \nAuthenticated ORCID iDs\n, which means that each researcher signs into their ORCID account and authorizes your system to obtain their iD. \nLearn more about Authenticated iDs\n\n\nRecord access permission\n\n\nControl over access to data in your ORCID record is one of \nORCID's core princples\n. While you can read public ORCID data without the record owner's involvement, some API actions require permission:\n\n\n\n\nGet an Authenticated ORCID iD\n\n\nRead non-public data (items with privacy set to 'Trusted parties')\n\n\nAdd/update record data\n\n\n\n\nCustom integration\n\n\nThe most customizable way to get Authenticated iDs is by building your own API integration. In this section, we'll walk through the steps that your own custom integration would need to complete in order to get an authenticated iD and record access permission.\n\n\nOAuth 2.0\n\n\nGetting an Authenticated iD and record access permission from a user involves following \nOAuth 2.0\n, an industry-standard protocol for authorization. OAuth allows a user to give a website or application access to account information stored on another site, without giving that site their password.\n\n\nIf you've ever signed into a site using Google or Facebook instead of your credentials for that particular site, you've already used OAuth!\n\n\nThe OAuth process includes 3 steps:\n\n\n\n\nCreate an authorization URL\n\n\nGet an authorization code\n\n\nExchange the authorization code for an access token\n\n\n\n\nGet API credentials\n\n\nAPI credentials consisting of a \nclient ID\n and a \nclient secret\n are needed in order to get Authenticated iDs and/or user permissions.\n\n\nTo get Authenticated iDs, you can use Public or Member API credentials. To get permission to read non-public information or add/update researchers' ORCID records, you'll need Member API credentials.\n\n\nFor this tutorial, please use your own sandbox API credentials:\n\n\nTo request API credentials, see \nRequest API credentials\n\n\n(Demo client secret created for this tutorial - do not share API client secrets!)\n\n\nCreate an authorization URL\n\n\nTo kick off the OAuth process, we'll need to create a special authorization URL that sends users to an ORCID sign-in screen. This URL consists of \nAuthorization endpoint\n, plus \nParameters\n that identify your organization and the permissions you want to request.\n\n\nAuthorization endpoint (Sandbox)\n\n\nhttps://sandbox.orcid.org/oauth/authorize\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\nExample\n\n\n\n\n\n\n\n\n\n\nclient_id\n\n\nYour Member or Public API client ID (issued by ORCID)\nTo request API credentials, see \nRequest API credentials\n\n\n[APP-*****************]\n\n\n\n\n\n\nresponse_type\n\n\n\n\ncode\n\n\n\n\n\n\nscope\n\n\nAPI action(s) you want to request permission for, from the list of \nORCID Scopes\n.\n\n\n/authorize\n \n \n/activities/update\n\n\n\n\n\n\nredirect_uri\n\n\nPage on your site that users will see after they complete the authorization process (must be on the list of allowed redirect URIs you specified when requesting your API credentials)\n\n\nhttps://developers.google.com/oauthplayground\n\n\n\n\n\n\n\n\nTo request permission to add/update activities (affiliations, funding, works, peer review items), our authorization URL will be:\nEnter you own client ID where it says [APP-\n*\n*\n***]\n\n\nhttps://sandbox.orcid.org/oauth/authorize?client_id=[APP-****************]\nresponse_type=code\nscope=/read-limited%20/activities/update%20/person/update\nredirect_uri=https://developers.google.com/oauthplayground\n\n\n\n\nGet an authorization Code\n\n\n\n\n\n\nIn a new window or tab, visit remebering to fill in your own APP\n\n\nhttps://sandbox.orcid.org/oauth/authorize?client_id=[APP-\n*\n*\n***]\nresponse_type=code\nscope=/read-limited\nredirect_uri=https://developers.google.com/oauthplayground\n\n\n\n\n\n\nAn ORCID sign-in screen listing the requested permissions will appear; sign into your Sandbox account and click \nAuthorize\n\n\n\n\n\n\nAfter granting permission, you'll be redirected to the Google OAuth Playground. A 6-character code will appear at the end of the redirect URI in the browser address bar (and under the \nStep 2\n section at left)\n\n\n\n\n\n\n\n\nExchange authorization code for access token \n authenticated iD\n\n\nOnce you have an Authorization Code, you can exchange it for an Access Token and the Authenticated iD of the user who signed in, which you'll need in order to take the API action(s) you requested permission for.\n\n\nIn a real-world situation, this exchange would be done by your system, using a programming language such as PHP, Java, or Ruby on Rails. For this tutorial, we'll use Google OAuth Playground to simulate a web application.\n\n\n\n\nClick the gear icon in the upper right corner to open the \nOAuth 2.0 Configuration\n\n\n\n\nEnter the following settings and click \nClose\n\n\n\n\n\n\n\n\n\n\nField\n\n\nValue\n\n\n\n\n\n\n\n\n\n\nOAuth flow\n\n\nServer-side\n\n\n\n\n\n\nOAuth endpoints\n\n\nCustom\n\n\n\n\n\n\nAuthorization endpoint\n\n\nhttps://sandbox.orcid.org/oauth/authorize\n\n\n\n\n\n\nToken endpoint\n\n\nhttps://sandbox.orcid.org/oauth/token\n\n\n\n\n\n\nAccess token location\n\n\nAuthorization header w/Bearer prefix\n\n\n\n\n\n\nOAuth Client ID\n\n\n[APP-*****************]\n(Demo client ID created for this tutorial)\n\n\n\n\n\n\nOAuth Client Secret\n\n\n0000000-0000-0000-0000-000000000000\n(Your own client secret created earlier - do not share API client secrets!)\n\n\n\n\n\n\n\n\n\n\nIn the \nStep 2 Exchange authorization code for tokens\n section at left, click \nExchange authorization code for tokens\n\n\n\n\nYour Access Token and Authenticated iD will appear \nRequest/Response\n section at right.\n\n\n \n\n\n\n\nOnce you have gone through this process once and you have the token this is all that you need to do further api calls for this ORCID and for these permissions. If you want to make calls for another ORCID or you want to write to a record where before you have only read for example, then you will need to complete the process again and get a new token.",
0 commit comments