Confirm your new email address

Finishes the address change users.email_change.start began: with the six-digit code from the email to the new address, your account moves to that address. Every other session of yours is signed out (keep stays signed in: the console passes the session you're using), a notice goes to the old address and a confirmation to the new one, and the organizations you belong to see user.email_changed (both addresses masked).

Each change allows 5 guesses (email_change_code_invalid, with details.attemptsLeft); after the fifth wrong one the change is canceled and needs a new code. Codes work for 10 minutes (email_change_expired).

If you sign in with Google or Microsoft, that keeps working. What doesn't follow the address: invitations sent to the old address can't be accepted with this account (ask for a new one), and an email code for the old address now starts a new, separate account.

Who can call it: the signed-in user, for their own account, in the console, with a sign-in in the last 15 minutes.

At a glance

REST: POST /api/v1/users/me/email_change/confirm
MCP tool: users_email_change_confirm
Operation ID: users.email_change.confirm
Scope: Platform
Permission: account:write
Risk tier: security
Dry run: Not supported
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the account:write scope
Fresh sign-in: In the console, a sign-in within the last 15 minutes
Since: M13

Request

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`code`	string	Yes	The six-digit code from the email to the new address (spaces and dashes are ignored).
`keep`	`ses_…` ID	No	The session that stays signed in: the console passes the one you're using. Every other session ends; without it, every session does.

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"email_change"`
`email`	string	Your account's address now.
`previousEmail`	string	The address it had until now.
`changedAt`	date-time
`sessionsEnded`	integer (at least 0)	How many of your other sessions were signed out.

Examples

Confirm with the code, keeping this browser signed in

HTTP

POST /api/v1/users/me/email_change/confirm
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "code": "482 913",
  "keep": "ses_01m4tx5nj8emwbyf7y9vcf47xc"
}

Response (200):

JSON

{
  "object": "email_change",
  "email": "ana.novak@example.com",
  "previousEmail": "ana@acme.example",
  "changedAt": "2026-11-04T09:00:00.000Z",
  "sessionsEnded": 1
}

Errors

Code	HTTP status	When	What to do
`email_change_code_invalid`	400	The code isn't right (`details.attemptsLeft`).	Enter the newest code we emailed to your new address. After 5 wrong codes the change is canceled: start it again.
`email_change_expired`	404	No change is waiting for a code, or its code has expired.	Start the change again to get a new code. Codes work for 10 minutes.
`email_taken`	409	Another account got the new address meanwhile (or had it all along).	Sign in with that address and delete that account or change its address first, or use another address.
`session_not_found`	404	`keep` isn't the session you're calling from.	Reload your account page to see the sessions that are still active.
`email_change_not_allowed`	403	You're platform staff.	Staff addresses follow the staff domains and your Google or Microsoft account. Ask a platform admin to change it.
`version_conflict`	409	Your account changed at the same moment; retry.	Fetch the object again and retry the change.
`email_change_unavailable`	500	The platform isn't set up yet.	Try again later. If it persists, contact support with the request ID.
`fresh_auth_required`	403	Your last sign-in is older than 15 minutes: sign in again first.	Sign in again, then repeat the action within 15 minutes.
`permission_denied`	403	The caller isn't a person signed in to the console.	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: validation_failed, api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, resource_not_found, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

Confirm with the code, keeping this browser signed in#

Errors#