Is the access token actually necessary with the public API?

[Steve]

Hi, I'm new to working with ORCID, I'm digging around in the sandbox, and I have a few questions.

Despite the documentation indicating that an access token is necessary, I am able to access the same data through the public API with and without a token.

Question 1:  Is an access token really necessary with the public API?

Question 2:  With non-member credentials, is anything possible besides getting a validated ORCID iD (and viewing public data that you don't seem to need credentials for anyway)?

[Chun Ly]

Hi Steve,

I don't use the Public API as often as the Member API. But to answer your questions, I think one reason you would want a token with the public API is to enable SSO into ORCID using institutional systems.

Also, while you can access the public API data, if your research is specific to individuals (e.g., at your organization), then it would be best to conduct authentication to ensure you have the proper ORCID iD rather than guessing or searching by name.

Cheers,

- Chun

Research Data Developer

Princeton Plasma Physics Laboratory

Performance Assurance & Contract Management

ORCID: 0000-0002-4245-2318

--
You received this message because you are subscribed to the Google Groups "ORCID API Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to orcid-api-use...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/orcid-api-users/29a196bc-17b7-438e-84c7-71ad060c11c0n%40googlegroups.com.

[Steve]

Right, I understand the value of getting an authenticated iD, but an access token isn't necessary for that.  An authorization code is returned (e.g., "eUeiz2") during the OAuth process, which is exchanged for an access token and authenticated ORCID iD, which are both returned in the same response.  At that point, I have the user's authenticated ORCID iD, so what good is the access token (again, for the public API)?

Ultimately, we're going to be using the member API, but I want to understand the differences, and at this point I'm trying to square what the documentation says with how the API actually behaves.

[Jason]

Kia ora | Hi Steve,

When you say that an access token isn't required for accessing the public API, I'm assuming that you are using an access token, just that it's a read-public one rather than one obtained from authentication?!  If you really are accessing the API without any access token, can you please give an example of what your doing?

You're doing a 3-legged OAuth exchange with permissions set by the scope, so what the token can be used for depends what scope you're requesting at the beginning. See here: https://info.orcid.org/documentation/integration-guide/getting-started-with-your-orcid-integration/#easy-faq-2569

With a plain scope=\authenticate you'll get an access token that can only be used for reading public items from the ORCID iD that granted it, and which will be invalid against any other.  I agree that this doesn't seem very useful on the surface cf a global read-public token, but at a minimum using it allows you to assure that you still have permission from the record holder, i.e., if they revoke that permission a read attempt with the access token against their record will fail.

Make sense?

Cheers,

J.  

[Steve]

Hi Jason,

That's certainly how I interpreted the documentation as well.

Here are two curl commands; I'll use the /email endpoint here only because the output is shorter to post, but it works the same way with the full record summary.

No token:

$ curl -s -H "Accept: application/json" https://pub.sandbox.orcid.org/v3.0/0000-0002-5223-2976/email
{"last-modified-date":{"value":1645088530980},"email":[{"created-date":{"value":1644508040488},"last-modified-date":{"value":1645088530980},"source":{"source-orcid":{"uri":"https://sandbox.orcid.org/0000-0002-5223-2976","path":"0000-0002-5223-2976","host":"sandbox.orcid.org"},"source-client-id":null,"source-name":{"value":"Zachary McKraken"},"assertion-origin-orcid":null,"assertion-origin-client-id":null,"assertion-origin-name":null},"email":"zach.m...@mailinator.com","path":null,"visibility":"public","verified":true,"primary":true,"put-code":null}],"path":"/0000-0002-5223-2976/email"}

Token:

$ curl -s -H "Accept: application/json" -H "Authorization: Bearer 01287878-5a18-450c-951d-f54c94dd2690" https://pub.sandbox.orcid.org/v3.0/0000-0002-5223-2976/email
{"last-modified-date":{"value":1645088530980},"email":[{"created-date":{"value":1644508040488},"last-modified-date":{"value":1645088530980},"source":{"source-orcid":{"uri":"https://sandbox.orcid.org/0000-0002-5223-2976","path":"0000-0002-5223-2976","host":"sandbox.orcid.org"},"source-client-id":null,"source-name":{"value":"Zachary McKraken"},"assertion-origin-orcid":null,"assertion-origin-client-id":null,"assertion-origin-name":null},"email":"zach.m...@mailinator.com","path":null,"visibility":"public","verified":true,"primary":true,"put-code":null}],"path":"/0000-0002-5223-2976/email"}

They both return the same response body.

--steve

[Chris Shillum]

Hi

ORCID supports token-less access to a record's public data via content negotiation. This means that you can request the PUBLIC JSON, XML or JSON-LD metadata directly from the URI version of an ORCID identifier by specifying the content type in a HTTP Accept header. More info here

[Jason]

Huh, thanks for the pointer to the docs Chris. 

I'd not noticed this despite it being up for 4 years :).

Also explains why we've had ORCID staff here on the group before asking whomever was hammering the registry if they could kindly stop, as at the time I thought you must have a view on exactly who's calling the API.

Ngā mihi | Thanks

Jason

[Steve]

Content negotiation is orthogonal to authorization/authentication.  It typically determines the format of the information, not access to the information (aside from unsupported content types).  What does content negotiation have to do with "token-less access?"  Is there a valid Accept header (or lack thereof) for which the public ORCID API would refuse to return data without the presence of a valid access token?

Nevertheless, I compared the responses of an ORCID record using all combinations of no Accept header, the Accept headers in the documentation, with and without an access token:

• In the absence of an "Accept" header, the default content type of the response is "application/vnd.orcid+xml".
• All endpoints behave the same with and without an access token.
• All three of the "xml" responses are the same (and the same as the response with no "Accept" request header).
• The first three JSON responses are the same after normalization (the first has no insignificant whitespace, the other two are "pretty printed").
• Incidentally, "text/turtle" and "application/n-triples" both cause a 500/Internal Server Error.  For "application/rdf+xml", the response is a 406 (Not Acceptable), although the body references 400, 405, and 415.

Can anyone give me a specific, working, tested example of the public ORCID API actually refusing to return user data with a "public" visibility in the absence of a valid access token?  The API documentation really seems to think you do, but I haven't found that it behaves in this manner, and without evidence to the contrary, I think we can conclude that the documentation is just inaccurate/misleading.

--steve

[Chris Shillum]

Steve

I am not sure what your concern/point is. We do have work on our backlog to clarify this a little in our documentation. But is there something you would like to be able to do that you are not able to do?

Regards

Chris

[Steve]

On Wednesday, February 23, 2022 at 2:28:49 PM UTC-6 Chris wrote:

I am not sure what your concern/point is. We do have work on our backlog to clarify this a little in our documentation. But is there something you would like to be able to do that you are not able to do?

Short answer: No, I've been working with the sandbox API(s) for a week now; I get how they work, in spite of the documentation.

Long answer:  I started by reading the documentation (shocking, I know).  I don't think it's controversial to say that it really pounds home how you need to get a user's permission for the "/read-public" scope and use the access token, even with the public API.  Yet pretty quickly I realized that you don't need an access token whatsoever for public data, so I thought I'd just confirm this with people who use the API to see if I was missing something.

 

I was expecting something along the lines of "Oh, yeah, the documentation's wrong; you don't need an access token for public data," or "Sort of, but there is a situation where you need to send the token otherwise you don't get public data... <goes on to explain this hypothetical scenario>," or "Yeah, it used to be that way but it changed," or maybe even "Holy crap, that's a bug; I can't believe we deployed our API with this massive security hole!", something that acknowledged the blatant difference between the documented and actual behavior.

As far as I can tell, an access token with the "/read-public" (or "/authenticate", which implicitly includes "/read-public") scope is completely useless.  You can get users' publicly-available data without any access token whatsoever, and users can't revoke access to public data (without changing its visibility, that is).

 

If you're putting documentation corrections on your backlog, here are some more to add, if they're not there already:

I started out with the "How does 3-legged OAuth work," which, in the first paragraph -- "Any integration can ask for read permissions using the Public API. ORCID members can use the Member API to ask for update permissions." -- seems to indicate that public (i.e., non-member) credentials can be used to get read permissions (I would read this as including "/read-limited" permissions, basically everything but writing data, especially when followed by that second sentence) and that permissions for reading publicly-visible data could be revoked by the user.  That really set me off on the wrong foot with a whole lot of misconceptions.

And here:  https://info.orcid.org/documentation/api-tutorials/api-tutorial-read-data-on-a-record/

        Method: GET
        Accept: application/vnd.orcid+xml
        Authorization type and Access token: Bearer [Stored access token]
        URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/record
The authorization header is actually "Authorization: Bearer [access token]".  It took me awhile to find the real header.  The docs give an accurate "Accept" header on the line above.  Why do they drop the ball with the "Authorization" header?  This is all over the place in the "info.orcid.org" docs.