import { Tabs, Callout, Steps } from "nextra/components";

# X

The X auth provider enables tools and agents to call the X (Twitter) API on behalf of a user.

<Callout>
  Want to quickly get started with X services in your agent or AI app? The
  pre-built [Arcade X MCP Server](/resources/integrations/social-communication/x) is what you
  want!
</Callout>

### What's documented here

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

This auth provider is used by:

- The [Arcade X MCP Server](/resources/integrations/social-communication/x), which provides pre-built tools for interacting with X
- Your [app code](#using-x-auth-in-app-code) that needs to call X APIs
- Or, your [custom tools](#using-x-auth-in-custom-tools) that need to call X APIs

## Configuring X auth

<Callout type="info">
  When using your own app credentials, make sure you configure your project to
  use a [custom user
  verifier](/guides/user-facing-agents/secure-auth-production#build-a-custom-user-verifier).
  Without this, your end-users will not be able to use your app or agent in
  production.
</Callout>

In a production environment, you will most likely want to use your own X app credentials. This way, your users will see your application's name requesting permission.


Before showing how to configure your X app credentials, let's go through the steps to create a X app.

### Create an X app

- Follow X's guide to [creating an app](https://developer.x.com/en/docs/x-api/getting-started/getting-access-to-the-x-api)
- Enable user authentication for your new app, and set its type to "Web App, Automated App or Bot"
- Set the redirect URL to the redirect URL generated by Arcade (see below)
- Copy the client ID and client secret to use below

Next, add the X app to Arcade.

## Configuring your own X Auth Provider in Arcade



<Tabs items={["Dashboard GUI"]}>
<Tabs.Tab>

### Configure X Auth Using the Arcade Dashboard GUI

<Steps>

#### Access the Arcade Dashboard

To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment.

#### Navigate to the OAuth Providers page

- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**.
- Click **Add OAuth Provider** in the top right corner.
- Select the **Included Providers** tab at the top.
- In the **Provider** dropdown, select **X**.

#### Enter the provider details

- Choose a unique **ID** for your provider (e.g. "my-x-provider").
- Optionally enter a **Description**.
- Enter the **Client ID** and **Client Secret** from your X app.
- Note the **Redirect URL** generated by Arcade. This must be set as your X app's redirect URL.

#### Create the provider

Hit the **Create** button and the provider will be ready to be used.

</Steps>

When you use tools that require X auth using your Arcade account credentials, Arcade will automatically use this X OAuth provider. If you have multiple X providers, see [using multiple auth providers of the same type](/references/auth-providers#using-multiple-providers-of-the-same-type) for more information.

</Tabs.Tab>
</Tabs>

## Using X auth in app code

Use the X auth provider in your own agents and AI apps to get a user token for the X 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 X:

<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="x",
    scopes=["tweet.read", "tweet.write", "users.read"],
)

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-12}
import { Arcade } from "@arcadeai/arcadejs";

const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable

const userId = "{arcade_user_id}";

// Start the authorization process
let authResponse = await client.auth.start(userId, "x", [
  "tweet.read",
  "tweet.write",
  "users.read",
]);

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 X auth in custom tools

You can use the pre-built [Arcade X MCP Server](/resources/integrations/social-communication/x) to quickly build agents and AI apps that interact with X.

If the pre-built tools in the X MCP Server don't meet your needs, you can author your own [custom tools](/guides/create-tools/tool-basics/build-mcp-server) that interact with the X API.

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

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

import httpx

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


@tool(
    requires_auth=X(
        scopes=["tweet.read", "tweet.write", "users.read"],
    )
)
async def post_tweet(
    context: ToolContext,
    tweet_text: Annotated[str, "The text content of the tweet you want to post"],
) -> Annotated[str, "Success string and the URL of the tweet"]:
    """Post a tweet to X (Twitter)."""
    url = "https://api.x.com/2/tweets"
    headers = {
        "Authorization": f"Bearer {context.authorization.token}",
        "Content-Type": "application/json",
    }
    payload = {"text": tweet_text}

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

        tweet_id = response.json()["data"]["id"]
        return f"Tweet with id {tweet_id} posted successfully. URL: https://x.com/x/status/{tweet_id}"
```