Skip to main content
POST
/
twitter
/
auth_twitter
Link an X/Twitter account (start OAuth)
curl --request POST \
  --url https://api.aisa.one/apis/v1/twitter/auth_twitter \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
{
  "auth_url": "https://twitter.com/i/oauth2/authorize?response_type=code&client_id=AIsa&redirect_uri=https%3A%2F%2Fapi.aisa.one%2Fapis%2Fv1%2Ftwitter%2Foauth_callback&scope=follows.write%20tweet.read%20users.read&state=0c2...d1f&code_challenge=...&code_challenge_method=S256",
  "state": "0c2ad1f...",
  "expires_at": "2026-04-18T07:00:00Z"
}
POST /apis/v1/twitter/auth_twitter is the first step for any X/Twitter write action routed through AIsa. It returns a short-lived X OAuth authorization URL — the source user opens it in a browser, approves the requested scopes, and X redirects back to AIsa’s fixed callback. AIsa stores the resulting session against your API key, and every subsequent write call (e.g., POST /twitter/follow_twitter) uses that session automatically.

​
When to call it

  • Once per source user, the first time you link their X account.
  • Again if the stored session is revoked, expired, or you need a different scope set.
You do not call it before every write request. The OAuth session persists against your AIsa API key.

​
Flow

1

Start the flow

Send POST /apis/v1/twitter/auth_twitter with your AIsa API key. Optionally include a scopes array in the body to request a narrower set than the default.
2

Open the auth URL

The response returns an auth_url and a state token. Open auth_url in the source user’s browser. X shows its standard “Authorize AIsa to access your account” screen.
3

User approves

After the user clicks Authorize, X redirects to AIsa’s fixed callback (https://api.aisa.one/apis/v1/twitter/oauth_callback). AIsa validates the state token, exchanges the authorization code for tokens, and stores the session against your API key.
4

Write endpoints unlock

From this point on, any call to a Twitter write endpoint using your AIsa API key acts on behalf of the linked source user. You never pass OAuth tokens in the body of those calls.

​
Default scopes

If you omit the scopes field, AIsa requests the full set needed for every Twitter write endpoint we expose:
  • follows.write — follow / unfollow
  • tweet.read — read tweets (required by most write actions)
  • users.read — resolve users, read profile info
  • tweet.write — post, reply, quote
  • like.write — like / unlike
  • dm.read — read DM threads
  • dm.write — send DMs
Pass a narrower array (e.g., ["follows.write", "tweet.read", "users.read"]) if you only need a subset. Write calls that require a missing scope return 403.

​
Expiry

The auth_url returned by this endpoint is short-lived (typically 10 minutes). If the user doesn’t complete the flow before expires_at, call POST /apis/v1/twitter/auth_twitter again to generate a fresh URL. The stored OAuth session itself lives longer (subject to X’s token rotation rules) and is refreshed automatically as long as the user doesn’t revoke access from X’s app settings.

Follow a user

First write endpoint that uses the session stored by this flow.

Twitter Autopilot skill

Agent skill that wraps the full read + write surface.

Authentication

AIsa API key lifecycle and storage best practices.

Authorizations

​
Authorization
string
header
required

Your AIsa API key. The authenticated source user (the account doing the follow) is determined by the OAuth session attached to your key.

Body

application/json
​
scopes
string[]

Optional list of X OAuth 2.0 scopes to request. Defaults to the set required by AIsa's Twitter write endpoints: follows.write, tweet.read, users.read, tweet.write, like.write, dm.read, dm.write.

Example:
["follows.write", "tweet.read", "users.read"]

Response

Authorization URL generated.

​
auth_url
string<uri>
required

Short-lived X OAuth authorization URL. Open it in a browser so the source user can approve the requested scopes.

​
state
string
required

Opaque CSRF state token that AIsa will validate when X redirects back to its callback. Store it client-side if you need to correlate the flow.

​
expires_at
string<date-time>

When the auth_url expires. Request a new one if the user hasn't completed the flow before this time.