This ORCID API tutorial covers the three things a developer needs to ship a working integration: obtaining OAuth credentials, choosing the correct read or write scope, and making a first authenticated call against the Sandbox. ORCID is a persistent digital identifier for researchers, and its API is a RESTful, OAuth 2.0-protected service returning record data as XML or JSON. This walkthrough assumes no prior OAuth experience and ends with a working call you can adapt into your own codebase.
CASRAI originated the CRediT contributor role taxonomy in 2014, and taxonomies like CRediT are frequently exchanged alongside ORCID iDs in manuscript-submission metadata — one reason developers build ORCID integrations in the first place. This guide focuses on the build steps: credentials, scopes and the first call, not a general product overview.
- Public API vs Member API: which one do you need?
- Setting up sandbox credentials
- OAuth 2.0 authentication and scopes
- Making your first API call
- Common integration patterns and CrossRef
- Answer-first Q&A
Public API vs Member API: which one do you need?
ORCID publishes two API tiers. The Public API is free to any registered developer and can authenticate users and read publicly visible record data. The Member API is available to ORCID member organisations and adds the ability to read limited-access data and write or update items on a record, with the researcher’s permission.
For a first integration — a “connect your ORCID iD” login button, or a script pulling public works — the Public API is sufficient. Only move to the Member API once your use case requires writing data back, such as auto-populating employment or works.
| Capability | Public API | Member API |
|---|---|---|
| Authenticate a user and get their ORCID iD | Yes | Yes |
| Read public data on a record | Yes | Yes |
| Read limited-access (trusted-party) data | No | Yes |
| Add or update items on a record | No | Yes |
| Requires ORCID membership | No | Yes |
Both tiers share the same stack: REST over HTTPS, OAuth 2.0 for authorisation, and XML or JSON for data exchange, per ORCID’s published API documentation.
Setting up sandbox credentials
Every integration should be built and tested against the ORCID Sandbox (sandbox.orcid.org) before touching production. The Sandbox mirrors production behaviour but isolates test data, and only sends verification email to Mailinator (@mailinator.com) addresses so it never spams real inboxes.
- Register a test account at sandbox.orcid.org and verify the email address — required before Developer Tools becomes visible.
- Open Developer Tools, accept the ORCID Public APIs Terms of Service, and click “Register for ORCID Public API Credentials”.
- Complete the application form: name, a URL describing the application, and a plain-language description shown to users on the consent screen.
- Add a redirect URI. Production requires HTTPS URIs that exactly match the registered domain, including subdomain.
- Save the application to generate a Client ID and Client Secret — the credentials used in every subsequent OAuth request.
Member API sandbox credentials, which unlock read-limited and write access for testing, are freely available even to organisations that are not yet ORCID members, according to ORCID’s integration guide.
OAuth 2.0 authentication and scopes
ORCID authentication runs on OAuth 2.0, and the flow you use depends on whether you need a one-off token or a token tied to an individual researcher’s consent.
Client-credentials flow (read-public)
For read-only access to public data with no user interaction, request a token using the client-credentials grant and the /read-public scope. This token is not tied to any one researcher and, per ORCID’s documentation, is valid for approximately 20 years and reusable across many calls.
Three-legged OAuth (read-limited and write)
To read limited-access data or write to a researcher’s record, you need their explicit consent via three-legged OAuth: the researcher is redirected to ORCID, signs in, and authorises your application for the requested scopes (for example /read-limited, /activities/update, or /person/update). ORCID redirects back to your registered URI with an authorisation code, which your server exchanges for an access token and the researcher’s authenticated ORCID iD.
Two structural points matter for a first build:
- The authorisation-code exchange must happen server-side — it cannot be completed inside a browser request.
- Scopes are requested up front in the authorisation URL and cannot be silently expanded later; if your integration later needs a broader scope, the researcher must re-authorise.
Making your first API call
With a Client ID, Client Secret and a chosen scope, the first call is a two-step HTTP exchange: get a token, then use it.
Step 1: request an access token
curl -i -L -H "Accept: application/json" \
-d "client_id=[Your-Client-ID]" \
-d "client_secret=[Your-Client-Secret]" \
-d "grant_type=client_credentials" \
-d "scope=/read-public" \
"https://sandbox.orcid.org/oauth/token"A successful response returns a JSON body containing an access_token, its scope, and its type (Bearer).
Step 2: call the record endpoint
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer [Your-Access-Token]" \
-X GET "https://pub.sandbox.orcid.org/v3.0/0000-0002-1825-0097/record"A 200 OK response returns the record summary in JSON (or XML, if you set the Accept header accordingly), including sections such as /person, /works, /employments and /fundings, each addressable individually by appending its endpoint name to the ORCID iD path. Individual items within those sections carry a “put code” that lets you retrieve or reference that specific item directly.
One frequently missed detail: querying a non-existent ORCID iD without a specific Accept header can still return a 200 response. Use content negotiation in production code so your integration can reliably detect a genuinely missing record.
Common integration patterns and CrossRef
Most production integrations fall into a handful of repeatable patterns rather than bespoke builds:
- Sign-in / iD collection — three-legged OAuth purely to authenticate a user and capture their ORCID iD for a manuscript or repository record.
- Read-and-display — pulling public works and affiliations to populate a researcher profile, typically via the client-credentials flow.
- Write-back — Member API integrations that add validated employment or works items to a record, requiring write scopes and consent.
- Bulk synchronisation — organisation-level jobs reconciling many records against an institutional system, generally built on Member API read-public access.
ORCID iDs also travel through scholarly-metadata pipelines: CrossRef accepts ORCID iDs as contributor identifiers in deposited metadata, so a publishing-system integration that collects an authenticated ORCID iD via the API can pass it straight into the CrossRef deposit, linking contributor identity across both registries without a second lookup. Request only the scope the workflow needs to avoid consent-screen friction during submission.
The ORCID GitHub organisation maintains reference tutorial materials, sample code, and the record schema definitions referenced throughout ORCID’s documentation — worth bookmarking alongside the Sandbox’s interactive Swagger interface for exploring endpoints before writing client code.
Answer-first Q&A
What OAuth scopes does the ORCID API support?
ORCID scopes include /authenticate and /read-public for identity and public data, /read-limited for trusted-party data with consent, and write scopes such as /activities/update and /person/update for Member API integrations. Scopes are requested explicitly in the authorisation URL and cannot be expanded after the fact without re-authorisation.
How long does an ORCID API access token last?
Access tokens issued by the ORCID API are long-lived, expiring approximately 20 years after issue, according to ORCID’s own developer documentation. This means a token can be stored and reused for repeated calls rather than refreshed on every request, simplifying server-side integration logic considerably.
Do I need to be an ORCID member to use the API?
No — the Public API is free to any developer with a verified ORCID account and covers authentication plus public-data reads. Only write access and limited-access reads require Member API credentials, which are issued to ORCID member organisations, though sandbox Member API testing is open to non-members.
Does the ORCID API integrate directly with CrossRef?
Not automatically — ORCID and CrossRef are separate registries that developers connect manually by passing an authenticated ORCID iD, collected via the ORCID API, into a CrossRef metadata deposit as a contributor identifier. There is no single combined API call; the integration is a data-passing pattern built across two independent systems.
Implications for institutional and publisher integrations
For teams commissioning integrations rather than writing the code, the practical takeaway is scope discipline: request the minimum OAuth scope the workflow needs, keep write-back integrations on the Member API with explicit researcher consent, and route identifier hand-off to CrossRef through the researcher’s already-authenticated ORCID iD rather than a second manual entry step. This reduces both consent-screen friction for researchers and audit surface for the integrating organisation.
As more manuscript-submission and repository systems adopt ORCID sign-in as a default identity layer, the scope decisions made at build time increasingly determine how much re-authorisation friction researchers face across every connected system down the line.
Leave a Reply