# Confirm your new email address

> The users.email_change.confirm operation: POST /api/v1/users/me/email_change/confirm in the REST API and the users_email_change_confirm tool in the MCP server.

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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#version_conflict)                   | 409         | Your account changed at the same moment; retry.                      | Fetch the object again and retry the change.                                                                      |
| [`email_change_unavailable`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).