import { Tabs } from "nextra/components";
import ToolFooter from "@/app/_components/tool-footer";
import { Callout, Steps } from "nextra/components";

# Twitch auth provider

<Callout type="info">
  At this time, Arcade does not offer a default Twitch Auth Provider. To use
  Twitch auth, you must create a custom Auth Provider with your own Twitch OAuth
  2.0 credentials as described below.
</Callout>

The Twitch auth provider enables tools and agents to call the Twitch API on behalf of a user.

### What's documented here

This page describes how to use and configure Twitch auth with Arcade.

This auth provider is used by:

- Your [app code](#using-twitch-auth-in-app-code) that needs to call Twitch APIs
- Or, your [custom tools](#using-twitch-auth-in-custom-tools) that need to call Twitch APIs

## Configuring Twitch auth

### Create a Twitch app

- Twitch requires that you have two-factor authentication enabled for your account. Enable in your [account security seetings](https://www.twitch.tv/settings/security)
- Create a Twitch Application in the [Twitch App Console](https://dev.twitch.tv/console/apps)
- Set the OAuth Redirect URL to the redirect URL generated by Arcade (see below)
- Select your Application category
- Select the 'Confidential' Client Type
- Copy the App key (Client ID) and App secret (Client Secret), which you'll need below

Next, add the Twitch app to Arcade.

### Configuring Twitch auth with the Arcade Dashboard

1. Navigate to the OAuth section of the Arcade Dashboard and click **Add OAuth Provider**.
2. Select **Twitch** as the provider.
3. Choose a unique **ID** for your provider (e.g. "my-twitch-provider") with an optional **Description**.
4. Enter your **Client ID** and **Client Secret** from your Twitch app.
5. Note the **Redirect URL** generated by Arcade. This must be set as your Twitch app's OAuth Redirect URL.
6. Click **Save**.

When you use tools that require Twitch auth using your Arcade account credentials, Arcade will automatically use this Twitch OAuth provider.


## Using Twitch auth in app code

Use the Twitch auth provider in your own agents and AI apps to get a user-scoped token for the Twitch API. See [authorizing agents with Arcade](/get-started/about-arcade) to understand how this works.

Use `client.auth.start()` to get a user token for the Twitch API:

<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
<Tabs.Tab>

```python {8-12}
from arcadepy import Arcade

client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable

user_id = "{arcade_user_id}"

# Start the authorization process
auth_response = client.auth.start(
    user_id=user_id,
    provider="twitch",
    scopes=["channel:manage:polls"],
)

if auth_response.status != "completed":
    print("Please complete the authorization challenge in your browser:")
    print(auth_response.url)

# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)

token = auth_response.context.token
# Do something interesting with the token...
```

</Tabs.Tab>

<Tabs.Tab>

```javascript {8-10}
import { Arcade } from "@arcadeai/arcadejs";

const client = new Arcade();

const userId = "{arcade_user_id}";

// Start the authorization process
const authResponse = await client.auth.start(userId, "twitch", {
  scopes: ["channel:manage:polls"],
});

if (authResponse.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(authResponse.url);
}

// Wait for the authorization to complete
authResponse = await client.auth.waitForCompletion(authResponse);

const token = authResponse.context.token;
// Do something interesting with the token...
```

</Tabs.Tab>

</Tabs>

## Using Twitch auth in custom tools

You can author your own [custom tools](/guides/create-tools/tool-basics/build-mcp-server) that interact with the Twitch API.

Use the `Twitch()` auth class to specify that a tool requires authorization with Twitch. The `context.authorization.token` field will be automatically populated with the user's Twitch token:

```python {5-6,9-13,36}
from typing import Annotated, Optional

import httpx

from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import Twitch


@tool(
    requires_auth=Twitch(
        scopes=["channel:manage:polls"],
    )
)
async def create_poll(
    context: ToolContext,
    broadcaster_id: Annotated[
        str,
        "The ID of the broadcaster to create the poll for.",
    ],
    title: Annotated[
        str,
        "The title of the poll.",
    ],
    choices: Annotated[
        list[str],
        "The choices of the poll.",
    ],
    duration: Annotated[
        int,
        "The duration of the poll in seconds.",
    ],
) -> Annotated[dict, "The poll that was created"]:
    """Create a poll for a Twitch channel."""
    url = "https://api.twitch.tv/helix/polls"
    headers = {
        "Authorization": f"Bearer {context.authorization.token}",
        "Client-Id": "your_client_id",
        "Content-Type": "application/json",
    }
    payload = {
        "broadcaster_id": broadcaster_id,
        "title": title,
        "choices": [{"title": choice} for choice in choices],
        "duration": duration,
    }

    async with httpx.AsyncClient() as client:
        response = await client.post(url, headers=headers, json=payload)
        response.raise_for_status()
        return response.json()
```

<ToolFooter pipPackageName="arcade_twitch" />