Register Session API

POST customer/session stores an X account's auth_token and ct0 cookies against your API key so subsequent write actions (like, retweet, bookmark, follow, tweet create/delete) and private reads (home timeline, bookmarks, DMs, followers-you-know) execute as that account without resending credentials. It returns ok (boolean), a confirmation message, and the resolved username, or null if resolution fails. The call is free.

curl -X POST "https://example.com/customer/session" \  -H "Content-Type: application/json" \  -d '{    "auth_token": "string",    "ct0": "string"  }'

{  "ok": true,  "message": "Session registered. Private-data endpoints will read as your account.",  "username": "myhandle"}

{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}

{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}

{  "error": "forbidden",  "message": "The acting account is not authorized for this write action, or has no logged-in session."}

{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}

{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}

{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

When to use

Call this once before any write action (like, retweet, bookmark, follow, tweet, delete) or private-data read (home timeline, bookmarks, likes, DMs, followers-you-know) so those calls run as your X account. Skip it only if you prefer sending auth_token and ct0 as x-auth-token and x-ct0 headers on each individual call instead of storing them.

Notes

• Re-calling with new cookies replaces the stored session. Stored auth_token and ct0 are encrypted at rest with AES-256-GCM and persist until replaced or deleted; to remove them, call POST /customer/session/delete, which is free and scoped to your own API key. There is no automatic expiry today.
• Per-call alternative (no registration): send the same credentials as x-auth-token and x-ct0 request headers (optional x-user-agent and x-proxy-url), or as auth_token / ct0 JSON body fields on a POST. Accepted on sixteen endpoints: tweet/create, tweet/delete, user/bookmarks, user/bookmark_search, user/blocking, user/muting, dm/list, dm/conversation, article/create, article/update_title, article/update_cover_media, article/update_content, article/publish, article/unpublish, article/list, article/delete. Anywhere else the headers are ignored and the call runs on the registered session. This lets one API key act as many accounts. Inline credentials are never stored.
• For write actions, pass x-proxy-url (or ?proxy=, or a proxy / proxy_url body field, or set proxy_url here) so the request egresses through a residential proxy. A per-call value wins over the session's registered one for that request. Writes from a datacenter IP are commonly soft-blocked by X as automated.
• Sessions expire when X invalidates them (password change, sign-out, security events). Re-register, or send fresh inline credentials, when private or write calls return session_dead.
• Copy auth_token and ct0 from the same browser request; ct0 rotates per page load and mismatched values will not work.

Related endpoints

• Revoke Session: Delete the auth_token and ct0 you registered, so we no longer hold your X session cookies. Self-serve, idempotent, and free.
• User Login: Log in to X with a username and password (plus TOTP for 2FA) and store the resulting session against your API key, so authenticated-account reads and write tools then act as that account. A convenience alternative to bringing your own cookies via Register Session.

FAQ

What does proxy_url do?

It sets the proxy your session's traffic egresses through, as a full HTTP, HTTPS or SOCKS5 URL with any credentials inline, for example http://user:pass@host:port. It is a property of the session rather than of a call, so once registered every request made with that API key on that session uses it, reads as well as writes. Omit it and the session is stored as direct, which means we pick the egress.

Can I set a proxy on a single call instead?

On write endpoints, yes. They accept a per-call proxy as the ?proxy= query parameter, an x-proxy-url header, or a proxy or proxy_url field in the JSON body, and a per-call value takes precedence over the session's registered one for that request only. Read endpoints have no standalone per-call proxy; they use the session's proxy_url, or the x-proxy-url sent alongside per-request credentials.

Can I use the API without registering my cookies at all?

Yes. Send auth_token and ct0 on each request, as x-auth-token and x-ct0 headers or as JSON body fields on a POST, and they are used for that single call and never written to storage. Sixteen endpoints accept them: tweet/create, tweet/delete, user/bookmarks, user/bookmark_search, user/blocking, user/muting, dm/list, dm/conversation, article/create, article/update_title, article/update_cover_media, article/update_content, article/publish, article/unpublish, article/list and article/delete. Everywhere else the headers are ignored and the call runs on the key's registered session.

How are registered cookies stored, and how do I get them deleted?

auth_token and ct0 are stored against your API key and encrypted at rest with AES-256-GCM, and the read path refuses a value it cannot decrypt rather than using it as-is. They persist until you replace them by re-registering on the same key, or delete them yourself with POST /customer/session/delete, which is free and scoped to your own key. There is no automatic expiry today.