X auth provider

The X auth provider enables tools and agents to call the X (Twitter) API on behalf of a user. Behind the scenes, the Arcade Engine and the X auth provider seamlessly manage X OAuth 2.0 authorization for your users.

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 toolkit, which provides pre-built tools for interacting with X
• Your app code that needs to call X APIs
• Or, your custom tools that need to call X APIs

Configuring X auth

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.

You can use your own X credentials in both the Arcade Cloud and in a self-hosted Arcade Engine instance.

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
• Enable user authentication for your new app, and set its type to “Web App, Automated App or Bot”
• Set the redirect URL to: https://cloud.arcade.dev/api/v1/oauth/callback
• Copy the client ID and client secret to use below

Next, add the X app to your Arcade Engine configuration. You can do this in the Arcade Dashboard, or by editing the engine.yaml file directly (for a self-hosted instance).

Configuring your own X Auth Provider in Arcade

There are two ways to configure your X app credentials in Arcade:

1. From the Arcade Dashboard GUI
2. By editing the engine.yaml file directly (for a self-hosted Arcade Engine)

We show both options step-by-step below.

export X_CLIENT_ID="<your client ID>"
export X_CLIENT_SECRET="<your client secret>"

X_CLIENT_ID="<your client ID>"
X_CLIENT_SECRET="<your client secret>"

auth:
  providers:
    - id: default-x
      description: "The default X provider"
      enabled: true
      type: oauth2
      provider_id: x
      client_id: ${env:X_CLIENT_ID}
      client_secret: ${env:X_CLIENT_SECRET}

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 to understand how this works.

Use client.auth.start() to get a user token for X:

from arcadepy import Arcade
 
client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
 
user_id = "user@example.com"
 
# 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...

import { Arcade } from "@arcadeai/arcadejs";
 
const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
 
const userId = "user@example.com";
 
// 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...

Using X auth in custom tools

You can use the pre-built Arcade X toolkit to quickly build agents and AI apps that interact with X.

If the pre-built tools in the X toolkit don’t meet your needs, you can author your own custom tools 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:

from typing import Annotated
 
import httpx
 
from arcade.sdk import ToolContext, tool
from arcade.sdk.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}"