Start changing an account's root email

POST 
/accounts/:accountId/contacts/email/start

Begins changing the AWS account's root email address (the address that signs in as the account root user) by sending a one-time code to the new address.

This is step one of two. Nothing has changed when it returns: the account still has its old root email, and the change only takes effect once the code is presented to POST /accounts/{accountId}/contacts/email/accept. The code is delivered by AWS to the new address, so whoever holds that mailbox has to hand it back to you.

This is the most consequential operation in this API. The root email is the account's ultimate recovery path and its password-reset target. Point it at a mailbox nobody monitors, or at one that later disappears, and the account becomes unrecoverable. Prefer a monitored distribution list over a person's address.

An account whose root email cannot be read (an organization's management account is the usual case) cannot be changed either. Check primary_email_unsupported from POST /accounts/{accountId}/contacts/get before starting.

Prism does not validate the body: it is decoded only far enough to confirm it is valid JSON and forwarded as sent, so a missing or malformed email address is rejected upstream and reaches you as a 502.

Like the other five contacts operations, this one is a proxy to CloudKeeper's ops-service, is present on every deployment, and reports every upstream failure as a 502; see POST /accounts/{accountId}/contacts/get for the full explanation.

Request

Responses

200

The ops-service accepted the request and AWS sent a one-time code to the new address. The root email has not changed. Complete the change with POST /accounts/{accountId}/contacts/email/accept.

The response carries no data, and in particular no handle for the pending change: the new address you sent is what identifies it in step two, so keep it. message is the fixed string OTP sent to new email address.

400

The request body is not valid JSON. This is the only thing about the body that Prism checks; an absent or malformed email is forwarded and fails upstream as a 502.

401

Authentication failed: the X-API-Token header was missing, malformed, expired or not recognised.

This response is text/plain, not JSON. It is written by http.Error in the authentication middleware, which runs before any handler and therefore before anything that would build a JSON envelope. A client that unconditionally JSON-parses response bodies will fail on this one, so check the status code first.

403

The token is valid, but it is not allowed to act on this tenant.

An API token is minted inside one tenant and stays bound to it for life. Sending it to a path whose tenant segment names a different tenant is refused here, in middleware, before the operation runs, so this says nothing about the resource you asked for, only about which tenant the path named. Check the tenant server variable against the console the token was created in.

404

No tenant matches the tenant segment of the request path. An AWS account that does not exist is a 502, not a 404.

502

No code was sent. Every upstream outcome lands here: the ops-service is unreachable, this self-hosted install is not paired with CloudKeeper SaaS, the account does not exist, the account's root email cannot be managed, the address is already in use by another AWS account, or the payload was missing the address. message carries the upstream reason verbatim and is the only way to tell these apart.