Reset Password (two-step)

A two-step recovery flow for when you don't have (or can't read) the mailbox: you trigger the reset, the account owner reads the emailed code from their own inbox and hands it back, and we complete the reset and return fresh tokens. Because the owner reads the code, this works for any email provider — including Hotmail/Outlook, Gmail and Yahoo (which the auto-read User Login V2 can't handle).

It's effectively a "refresh the tokens" tool: it sets a new password we control and returns a fresh auth_token / ct0 / twid. Each step costs $0.005 per call.

Step 1 — Send the code

Triggers X's password-reset email for the account and returns a session_id.

Request Body

Response (200)

{
  "status": "success",
  "session_id": "1d171e717491ab...",
  "expires_in": 900,
  "message": "A password-reset code was emailed to the account. Submit it to /twitter/reset-password/confirm with this session_id."
}

The session_id is valid for ~15 minutes (the code's lifetime).

Step 2 — Confirm with the code

Completes the reset with the code the owner received, and returns fresh tokens plus the new password.

Request Body

Response (200)

Same shape as User Login V2:

{
  "username": "myaccount",
  "new_password": "Gx7hcuyxk5xr",
  "auth_token": "59bace0de501...",
  "ct0": "9959...",
  "twid": "u=155977652",
  "profile": { "...": "..." }
}

Error Responses

Errors include a code field:

Once the password is set, the flow is resumable: a missing/wrong totp_secret never loses new_password — retry 2FA with the same session_id rather than restarting.

When to use which

• User Login V2 — one call if you have the mailbox password and it's a supported provider (GMX/mail.com, Hotmail/Outlook).
• This two-step flow — when you don't have the mailbox password, the provider isn't auto-readable (Gmail/Yahoo), or the account owner is in the loop to read the code.

Example

# 1) send the code
curl -X POST "https://api.getxapi.com/twitter/reset-password/send-code" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "username": "myaccount" }'

# 2) confirm with the code the owner received
curl -X POST "https://api.getxapi.com/twitter/reset-password/confirm" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "<from step 1>", "code": "avfw47d9", "totp_secret": "SXGS5MN2IHUMV34H" }'