Authenticating with the Twitch API

Frequently Asked Questions
1

Introduction

So, you want to work with the Twitch API and you probably noticed that everything requires some sort of Authentication / Authorization to allow you to use it. This Post/Wiki aims to answer some FAQ about that procedure and help you along in your journey.

If you are already working with the API and are just struggling with Errors, scroll down to the Troubleshooting section.

If instead, you are new to the API entirely and want to learn more, just read on!

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: https://www.youtube.com/watch?v=t18YB3xDfXI
Give it a watch. Then come back here for some more tidbits.

For those more Text-Based or that just want a TL;DR: You are working on building an Application, referred to as a Client within OAuth. Your Application wants to access Data or certain Permissions, called a Scope, of a User that authorizes your application.

To get started, you will notice in the Docs references to your Client-ID, Redirect URI and Client Secret. You get / set these on the Developer Console. Feel free to set it up ahead of time, but be aware: If you delete an app, its name will become unavailable for a while, so if you plan to reuse the name for a new App, make sure to rename the old application first.

This “Application” will be your Client. Even if you plan to distribute your Application to other users or let your bot join other channels, this Client will stay the same. It is absolutely imperative that you do not distribute your Client Secret under any circumstances. It is a Password, treat it as such! Contrary, the Client-ID is openly known and there is no harm in sharing it.

Got your Client set up? Good! Next, you’ll want to decide which Flow you’ll want to use.

What Flow is the correct one for me?

Seen the Video? Understood roughly what we’re trying to do? Got your Client set up? 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: https://i.3v.fi/choosing-oidc-oauth-flow-dark.svg?s - Follow this flow chart to decide which Flow you will want to use. Some further context about it is also in the next paragraph.

App Access vs. User Access Token

In the end of a Flow, you will always receive a Token. This can be either of two (technically 3, but we ignore OIDC for brevity) types: An App Access Token or a User Access Token. Make sure that you know which one you are getting and which one you need - every Endpoint in the API lets you know which one it requires in the Documentation, but in general: If you need any scopes to access any specific User’s Data, you will need to get a User Access Token, so you cannot use the Client Credentials Flow. Contrary, EventSub requires an App Access Token whilst a user previously generated a User Access Token for your application.

For most “static lookup jobs” like fetching streams or looking up game info, an App Access Token will suffice as well, granted all other requirements for usage are met.

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.

But how exactly do i what now?

To reiterate: How exactly you implement your Authentication is entirely up to you, as you know your requirements and environment best.

However, there are examples for any of the flows on GitHub, courtesy of @BarryCarlyon:

Once you have your token, you can then send it and your Client-ID as headers to the Twitch API. Specifically, your plain Client-ID as a Header called Client-ID and, assuming your token is asdf1234, your token prefixed by "Bearer " in the Authorization header, as such:

Client-ID: askljbdljnkf98324unui092
Authorization: Bearer asdf1234

That should get you going! If you run into any issues, read along:

Troubleshooting

401 Responses

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 Twitch Chat Password Generator) 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 the section above!
  • 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!

I have no Client Secret on my Dashboard!

With the introduction of the Device Code Flow, all applications have been devided between “Public” and “Confidential” Applications. If you select “Public” for your Application, you do not get a Client Secret - you did affirm that you were unable to store Secrets for it, after all. As you cannot change the Type of an Application after creation, you are effectively locked to using the Implicit or Device Code Flows. Make sure you pick the correct Type upon App creation!

More Stuff

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!

4 Likes