Revoke Twitter Session API | Delete Stored Cookies

Revoke Session deletes the auth_token and ct0 stored against your API key. It is scoped to the caller, idempotent, and free, and returns 200 with deleted: true when a stored session was removed or deleted: false when nothing was stored. It removes our copy of the cookies; it does not log the account out of x.com.

curl -X POST "https://example.com/customer/session/delete"

{  "ok": true,  "deleted": true,  "message": "Your stored Twitter session was deleted. The auth_token and ct0 you registered are no longer on our servers. This does not log the account out of x.com: to invalidate the cookies themselves, revoke the session from your X account settings as well."}

{  "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": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue."}

{  "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 it when you want us to stop holding your X session cookies: you are done with a stored session, you are rotating cookies you would rather we did not keep, or a security review needs a self-serve deletion path rather than a support request. To swap in fresh cookies and keep working, re-register with POST /customer/session instead, which overwrites the stored row in place. If you only ever send credentials per call as x-auth-token and x-ct0, nothing is stored and there is nothing to revoke.

Notes

• Scoped to the caller by construction. The API key comes from the authenticated request context; the handler reads no api key, user id, username, or account id from the request itself, so a call cannot reach another key's stored session.
• Idempotent, and 200 either way. A second revoke, or a revoke by a key that never registered, returns 200 with deleted: false rather than a 404.
• Free. Priced at zero deliberately, so a customer whose balance is exhausted can still delete their stored credentials.
• Audited. Each call writes one row to your usage log under the slug customer/session/delete, recording when the revoke was asked for and whether a stored session was actually removed.
• It deletes our copy of the cookies and does not invalidate them at X. To kill the cookies themselves, revoke the session from your X account settings as well.
• A session that X rejected and we marked dead is still stored and still revocable. Marking it dead stops us serving with it; it does not remove the row.
• Per-call credentials sent as x-auth-token and x-ct0 headers are never stored, so a caller who only uses that path has nothing to revoke.
• To replace cookies rather than remove them, re-register with POST /customer/session: it overwrites the stored row in place, and there is one row per API key with no history kept.

Related endpoints

• Register Session: Register your auth_token and ct0 cookies once so every write and private read acts as your account, or pass them per call as x-auth-token / x-ct0 headers.
• 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

Does this log my account out of X?

No. It deletes our copy of auth_token and ct0. The cookies themselves stay valid at X, so if you want them killed as well, revoke the session from your X account settings.

What happens if I call it twice?

The second call returns 200 with deleted: false. Revoking twice is not an error, and neither is revoking when nothing was ever stored: your goal is that we no longer hold your cookies, and that is true in both cases.

Can one API key delete another key's session?

No. The handler takes the API key from the authenticated request context and reads no identity from the request itself, so there is no body field, query parameter, or second header that could name a different key. The stored session table is keyed on the API key, and the delete matches on that key alone.

Does revoking cost credits?

No, it is priced at zero. That is a security property rather than a discount: billing refuses a call with 402 when the balance is short, so a priced revoke would mean an account that ran out of credits could not delete its own credentials.

I send x-auth-token and x-ct0 on every call. Do I need this?

No. Per-call credentials are used for that single request and never written to storage, so there is nothing to revoke. Calling it anyway is harmless and returns deleted: false.

My session was marked dead. Is it still stored?

Yes. When X rejects a session as expired or deauthorized we mark it dead, which stops us serving with it. The row and the encrypted cookies stay until you replace them or revoke them, so a dead session is still worth revoking.

Is the revoke recorded anywhere?

Yes. Each call writes one row to your usage log under the slug customer/session/delete, including whether a stored session was actually removed, so there is a record of when the revoke was asked for.