Authenticating with the Twitch API

One of the most common set of issues developers stumble across when integrating with Twitch has to do with Authentication errors.

If you come across a 401 Unauthorized response from the Helix API, you are most likely doing something wrong or missed a step to achieve proper authentication.

Your first step should be to read the message body. The API will always give you a JSON body with a message attached that should explain the situation further.
The most common issues shall be listed below:

  • Client ID and Token do not match
    This indicates that you either did not correctly pass both the Client-ID and Authorization Headers or used a third-party website (like to generate your token.
    Make sure you did not accidentally typo’d either header and are passing the Token with the word Bearer in front of it, then seperated by a space your token.
    Like this: Authorization: Bearer abcdef1234 (*)
  • If you did use another service to generate your token, but are trying to use your own Client-ID, this will not work - you always must pass the Client-ID that was used to generate the token initially.
    If you need more information on how to get started generating your own token, see further below!
  • The same may happen if you accidentally tried to use a Code from the Authorization code flow instead of a Token. You will still need to exchange this Code for a Token, as described in step 3 here

(*) Note that the /validate Endpoint uses the OAuth prefix instead of Bearer!

Another common error:

  • Token invalid or missing required scope
    This indicates that your token does not have the required scopes. Each API Endpoint will list which scopes it requires, so make sure you requested it when generating the token.
  • Important distinction: You may also run into this error if you tried to use an App Access Token from the Client Credentials Flow, which can not be tied to any user or scope as it only represents an application, but does not grant permission to read any users private information as it is not tied to any specific user.
    Consider using any of the other two flows instead.
  • If you are still using the old v5 API (/kraken instead of /helix), you may also get this Error when using the Bearer prefix in the Authorization header - it uses OAuth instead, just like the /validate endpoint!

How to OAuth

If the Twitch API is the first time you are dealing with authentication through OAuth, it can seem quite intimidating at first, but don’t be alarmed, we’ve all been there! Once you understand its core functionality, you will be able to use it more quickly in the future.

First things first

While not absolutely required, you should probably try to get a general overview of how OAuth works, what it is trying to achieve and why it is doing what it is doing.
As good introduction, I can recommend this Video:
Give it a watch. Then come back here for some more tidbits.

What Flow is the correct one for me?

Seen the Video? Understood roughly what we’re trying to do? Good!
Next up, you will be faced by a decision: Which Flow is the one you should use?
I could write another paragraph, but this image by @3ventic sums it up quite nicely:

Made your choice? Good! Next, you’ll want to implement it, but how exactly you do that is entirely up to you - the Authentication Docs will be a good companion to keep open, if you haven’t seen them yet.

Last but not least, make sure you keep your secrets secret. Never share your client secret or tokens with anyone. They were granted to your Application and your Application only, so sharing them would be compromising the trust your users put in you.

If you have questions for anything described here or run into other troubles, don’t hesitate to join the TwitchDev Discord! We’re there to help you out!