Feedback about docs/errors

[skerpskerp]

I assume this is largely my unfamiliarity with OAuth2, but I’m finding some of the docs/error reporting to be pretty frustrating.

For example, if I pass'Client-ID: <my client id>' as a header to helix/users, I get the error:
Must provide a valid Client-ID or OAuth token

Which made me think my Client-ID was faulty.

The docs specify nothing about Client-ID, putting them at odds with the error message:

curl -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/helix/users?id=44322889'

(the example request)

And the only mention of Bearer token usage is as in a user’s token, to look up a single user without id or username.

Of course, in the end, it wants a user token for single user blind lookup, an app token for lookup-by-id, and has no interest in your client id whatsoever.

It would save some head scratching if a) the error message wasn’t misleading and b) the docs differentiated between when an endpoint wants a user token or an app token, and in the case of it accepting both, the use case for each.

[Dist]

@skerpskerp

For example, if I pass 'Client-ID: <my client id>' as a header to helix/users, I get the error:
Must provide a valid Client-ID or OAuth token

Maybe you’re not making the request correctly, because requests to that endpoint work perfectly fine here with just a Client-ID.

@skerpskerp

Of course, in the end, it wants a user token for single user blind lookup, an app token for lookup-by-id, and has no interest in your client id whatsoever.

You can use just a Client-ID, but you will have a greatly reduced rate limit compared to using a Bearer token.

As for what tokens an endpoint wants, an App Access Token will work with all endpoints that don’t require a user scope, and in the places where it’s specifically required (such as the Get Webhook Subscriptions endpoint) it does say in the docs that it requires an App Access Token.

Like an App Access Token, a User Access Token can also be used any endpoint (except ones strictly limited to App Access Tokens) to gain an increased rate limit, and in the case of endpoints that require user authorization of a specific scope to access an endpoint then they will be limited to just User Access Tokens as they are the only ones which a user can grant a scope to in the first place.

@skerpskerp

It would save some head scratching if a) the error message wasn’t misleading and b) the docs differentiated between when an endpoint wants a user token or an app token, and in the case of it accepting both, the use case for each.

It does, anything that says it requires a certain authorization scope implies that it requires a User Access Token. Endpoints that use the token to look up specific data based on that token implies that it’ll be a User Access Token when it’s an endpoint that returns user data, and in the case of the Webhook Subscription endpoint it explicitly states it needs an App Access Token. For all other endpoints where a token is a specific requirement, you can use either an App Access Token, a User Access Token, or a Client-ID (with its lower rate limits)