Contents

Get Started with the Twitch API

The Twitch API is a RESTful API that lets developers build creative integrations for the broader Twitch community.

To see how easy it is to integrate with the API, let’s use the Twitch CLI (command line interface) to get information about the TwitchDev user.

Step 1: Register an application

The first step is to register your app with Twitch. To register your app:

  1. Log in to the developer console using your Twitch account. If you don’t have an account, select the Sign Up tab to create one.
    • When you sign up for an account, Twitch sends you an email to verify your account. Be sure to open the email and verify your account before proceeding.
    • You must also enable two-factor authentication (2FA) for your account. To enable 2FA, open your profile and navigate to Settings, Security and Privacy, and follow the steps for enabling 2FA.
    • You’ll need to restart your console for these changes to take affect.
  2. Select the Applications tab and then click Register Your Application.
  3. Set Name to your application’s name. The name doesn’t matter for this exercise but it must be unique within all Twitch applications.
  4. Set OAuth Redirect URLs to the callback URL that your app uses for authorizations. For this example, use http://localhost. Then, click Add.
  5. Select the Category of application that your app belongs to. For this example, it doesn’t matter which category you select.
  6. Click the I’m not a robot checkbox.
  7. Click Create.
  8. Back in the Applications tab, locate your app under Developer Applications, and click Manage.
  9. Note your Client ID to use in Step 2.
  10. Click New Secret to generate a secret to use in Step 2.

Step 2: Authentication using the Twitch CLI

This example uses the Twitch CLI to generate an OAuth access token that’s required to access Twitch resources.

Installing the CLI

To install the Twitch CLI, go to the Twitch CLI repository and follow the Download instructions in README.md. For example, use the following Homebrew command to install the CLI on MacOS or Linux.

brew install twitchdev/twitch/twitch-cli

CLI usage

After installing the Twitch CLI, open a terminal window and enter twitch at the command prompt to display the CLI’s usage.

$ twitch
A simple CLI tool for the New Twitch API and Webhook products.

Usage:
  twitch [command]

Available Commands:
  api         Used to interface with the Twitch API
  configure   Configures your Twitch CLI with your Client ID and Secret
  event       Used to interface with Event services, such as Eventsub and Websub.
  help        Help about any command
  mock-api    Used to interface with the mock Twitch API.
  token       Logs into Twitch and returns an access token according to your client id/secret in the configuration.
  version     Returns the current version of the CLI.

Flags:
      --config string   config file (default is $HOME/.twitch-cli/.twitch-cli.env)
  -h, --help            help for twitch

Use "twitch [command] --help" for more information about a command.

If you have trouble installing or running the CLI, get help by posting a note in the #cli-help channel of the TwitchDev Discord server.

Getting an access token

To get an access token, enter twitch token at the command prompt. Because this is the first time you’re running the token command in this instance of the CLI, the CLI will prompt you for the client ID and secret you created in Step 1. After entering the ID and secret from Step 1, the CLI returns an access token that you’ll use in Step 3. (The access token is an app access token and is valid for 60 days.)

The following example shows the output from the token command.

$ twitch token
No Client ID or Secret found in configuration. Triggering configuration now.
Client ID: wbmytr93xzw8zbg0p1izqyzzc5mbiz
Client Secret: 5ykf41lduut2lvbcnu7zg1wjdhroiw
Updated configuration.
2021/07/30 20:20:06 App Access Token: 2gbdx6oar67tqtcmt49t3wpcgycthx

Note the access token, which you’ll use in Step 3 for the cURL exammple.

Step 3: Making your first Twitch API request

Now that the CLI is configured with your client ID, secret, and access token, you can make your first request. To get information about the TwitchDev user, enter the following Twitch CLI command:

twitch api get users -q login=twitchdev

For information about the api command and usage, see API usage.

The JSON response

The following example shows the JSON response that the request returns.

{
  "data": [
    {
      "broadcaster_type": "partner",
      "created_at": "2021-07-30T20:32:28Z",
      "description": "Supporting third-party developers building Twitch integrations from chatbots to game integrations.",
      "display_name": "TwitchDev",
      "id": "141981764",
      "login": "twitchdev",
      "offline_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/3f13ab61-ec78-4fe6-8481-8682cb3b0ac2-channel_offline_image-1920x1080.png",
      "profile_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/8a6381c7-d0c0-4576-b179-38bd5ce1d6af-profile_image-300x300.png",
      "type": "",
      "view_count": 6652509
    }
  ]
}

Using cURL to get the information

If you use cURL, here’s the call you’d use to get the TwitchDev user’s information (remember to change the Authorization and Client-id header values to your own values).

curl GET 'https://api.twitch.tv/helix/users?login=twitchdev' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Next steps

Check out the CLI’s API usage documentation and then try out a few different endpoints and options.

For a list of the endpoints that you can call, see Twitch API Reference.

To understand Twitch API concepts, see Twitch API Guide.

To get into the nuts and bolts of authentication, see the Authentication guide. This guide explains how to enable your application to take actions on behalf of a Twitch account, or access specific data about a user’s account.

Join our community of Twitch developers! And for other ways to connect with the community, explore our developer support page.