orcid.orgContact Info: p. +1-301-922-9062 a. 10411 Motor City Drive, Suite 750, Bethesda, MD 20817 USA

Getting connected with the ORCID API

Alainna Therese WrigleyORCID Community Engagement & Support

support@orcid.org | orcid.org/0000-0002-6036-0903

2

ORCID provides

orcid.org

Persistent digital identifiers to distinguish researchers from each otherMember-built integrations that connect researchers and their activities/affiliationsA hub for synchronizing machine-readable connections between identifiers for people, organizations, and research activities

✔ Plumbing for research information ✔ Tools to build trust in digital information

3

Organizations are use ORCID APIs to authenticate, collect, display, and connect persistent identifiers for people, places, and things in research workflows

ORCID enables assertions

orcid.org 4

The other things that need to happen• Communications• Roll-out timing• Encouraging use

…are as important and can be much harder than using the API

Let’s not get ahead of ourselves...

orcid.org 5

API (Application Programming Interface): an interface that lets one software program “talk” with another, exchanging data behind the scenes.

What is an API?

orcid.org 6

• Permissions/scopes: your contract with the user

• ORCID message (schema): format of the data exchanged

• OAuth calls – the permission protocol: how you “execute the contract”

• ORCID-specific calls: providing & receiving information with the registry

The ORCID API in a nutshell

PHOTO: 3/2 nuts © M.G. Kafkashttps://flic.kr/p/4XytpS

orcid.org 7

ORCID Public and Member APIs

API FeaturesPublic APIFreely available to anyone

• Authenticate: Get a user’s authenticated ORCID iD

• Read (Public): Search/retrieve public data• Create: Facilitate creation of new ORCID

records (via on-demand process)

Member APIORCID member organizations(Sandbox test environment freely available to anyone)

• Read (Limited): Search/retrieve "limited-access" data

• Add: Post new items to a record• Update: Edit or delete items you

previously added • Webhooks (Premium only): Receive

notifications of updates

orcid.org 8

Connecting to the ORCID Registry

Two models:1. Connect via a vendor system

• Manuscript submission/publication

• Document/data repositories• Profile systems• CRIS systems

2. Develop a custom connection

orcid.org 9

Custom integration

Via the ORCID APIs• Fine-tuned control and permissions• Customized buttons, user flows, &

user feedback

Current integration list: http://members.orcid.org/current-integrations

orcid.org 10

Vendor system integration

Publishing• eJournal Press• Editorial Manager• ScholarOne

Document / data repositories

• DSpace• ePrints• Hydra/Fedora

CRIS Systems• Converis• Elements• IRMA• Pivot• PlumX• Pure• Vivo

http://members.orcid.org/orcid-enabled-systems

May 3, 2023 orcid.org 11

Collect & Connect goals• Clarify how plumbing works• Standardize experience• Standard connection installation

guidelines• Increase predictability and trust in

the “utility”• Community approach to reliable

connections

May 3, 2023 orcid.org 12

Collect & Connect

May 3, 2023 orcid.org 13

Collect

Display Connect

SynchAuthenticate!

Collect

COLLECT validated ORCID iDs for individuals• Explain what ORCID is• Explain why you’re collecting iDs• Consistent user experience• Authenticated connections

May 3, 2023 orcid.org 14

Ensure individuals are correctly connected with your institutionConveris, Pure, Symplectic Elements, VIVO use the OAuth process

Display

May 3, 2023 orcid.org 15

DISPLAY iDs on your website, platform, systems• iDs shown as a link• iDs in metadata• Use the ORCID Member logo• Explain why iDs are collected

Signal that your systems are plumbed to support ORCID iDshttp://orcid.org/trademark-and-id-display-guidelines

Connect

May 3, 2023 orcid.org 16

CONNECT your data to ORCID Records• Request permission to write to Records• Store long-lived tokens• Add data that you uniquely can

(authoritative)• Explain the connection

Enable researchers to provide validated data to othershttps://orcid.org/blog/2015/10/26/auto-update-has-arrived-orcid-records-move-next-level

Synchronize

May 3, 2023 orcid.org 17

SYNCHRONIZE with your systems• Update information when it changes• Auto-add new information• Search & link wizards• Sync data from others

Saved time, better reporting, improved information flowhttps://members.orcid.org/api/tutorial-webhooks

https://orcid.org/blog/2015/10/26/auto-update-has-arrived-orcid-records-move-next-level

May 3, 2023 18

DISPLAY• In metadata• On sites• In publications

CONNECT• Affiliations (employers)• Works (publishers)• Awards (funders)

orcid.org

Collect & Connect flow

Get permission, use permission

ORCID Record

Yes!Do you have permission to do what you want to do?

Get the permission; store iD and “token”

Read the record or update the record

No

OAuth

May 3, 2023 19orcid.org

PHOTO: Job Meetingwww.flickr.com/photos/jobmeeting/14375164286

Involving the user

orcid.org

Key benefits:• You know the user controls the iD• User knows what’s going on/ user choice• Privacy/ data control trends• Position/ strengthen your system as a service

How?• Just a “fancy” URL• Prior iD not needed• Hard things: promotion, finding touch points

Get permission: touch points

Look for natural fits:• Your sign in – why not link

your iD?• Your account settings/ user

profile• Submission (of any type)• Form fills: pre-fill from your

Record!• Registration: for conference

or meeting• Reporting: Link your iD to

get started

Step 1: fancy URL

https://sandbox.orcid.org/oauth/authorize? \client_id=APP-XT8FBKJRO3MR8WDR& \response_type=code& \scope=/orcid-profile/read-limited%20/activities/update& \redirect_uri=https://my.URL.org& \ family_names=Researcher&given_names=Bob&email=bobresearcher@mailinator.com&orcid=0000-0001-6356-0580

The base URL – displays the screen

who’s asking?

what permission?where the user goes next

Personalize theexperience

The OAuth call: part I

Step 2: User feedback & Auth code

The magic code

ORCID sends the user to your redirect, with a codehttps://my.URL.org?htA3yE you... • Save the code – you need it for the next

step• Display something useful to the user

• Authorize: thanks for your permission!• Deny: are you sure you don’t want to give

permission?

Step 3a: Change code into token

Use the code to gain access using the ORCID APIhttps://api.orcid.org/oauth/tokenHEADER: accept:application/jsonDATA: client_id=APP-XT8FBKJRO3MR8WDR client_secret=e285575c-4794-464b-a807-6f1c06b63grant_type=authorization_codecode=htA3yEredirect_uri=https%3A%2F%2Fmy.URL.org

our API calls always looks like URLs (RESTful)

what format?

The magic codeconfirming that you arethe right one to get thisinformation

Step 3b: Store the result

The result of the call"access_token” :"6710dfee-6aab-445b-a266-205dd9085273","token_type” : "bearer","expires_in” : 631138518,"scope” : "/orcid-profile/read-limited /activities/update","orcid” : "0000-0001-6356-0580","name” : "Bob Researcher"

store the access token and iD

when permission expires (in seconds)

your permission – executed contract

iD & name for the person who gave permission

What you can do

✔ iD Collected!

You have the iD, now display it!

iDs in profiles

Get permission, use permission

ORCID Record

Yes!Do you have permission to do what you want to do?

Get the permission; store iD and “token”

Read the record or update the record

No

OAuth

May 3, 2023 27orcid.org

Connect to send data

• Read data: GET • Add data: POST• Update data: PUTBASE URL: https://sandbox.api.orcid.org/v1.2/0000-0001-6356-0580/affiliationsHEADERS: accept:application/json (reading) content-type:application/jsonAuthorization: Bearer 6710dfee-6aab-445b-a266-205dd9085273DATA (if adding or updating): the file location=@file_location_name

Relevant area: /orcid-bio,/funding

data format

Access token from before

Send data in ORCID Schema

User sees new info on record

API in action: Create on demand

http://orcid-create-on-demand.herokuapp.com

Where to go from here?• Membership

http://orcid.org/about/membership • Collect and connect documentation

https://members.orcid.org• ORCID API documentation

https://members.orcid.org/api• ORCID API bootcamp (step-by-step

introduction)https://github.com/alainna/VALA2016

• Technical webinarshttps://members.orcid.org/event-list

• ORCID Community Engagement & Support teamsupport@orcid.org