1. Docs
  2. API Reference
  3. Request an email-address change

Request an email-address change

POST/v1/auth/me/email

Starts a change of the signed-in administrator's email to new_email. The current email stays in use until the change is confirmed. A confirmation link valid for 24 hours goes to the new address and a notice goes to the current one. A new request replaces any pending one. An administrator with a second factor enrolled must present a fresh X-Mfa-Step-Up-Token (401 with mfa.step_up_required or mfa.step_up_invalid otherwise); one without a factor omits it. Refuses with 400 when the address is the current one or the account signs in only through SSO and has no password (auth.email_change_sso_managed). An address another user already has gets the same answer as a free one and no link, so the request never says whether an address is registered; the change is refused at confirmation. Limited to 5 requests a minute.

Headers

  • x-mfa-step-up-token

    The step-up token `POST /v1/auth/mfa/step-up` returned. Required when the administrator has a second factor enrolled; one with none omits it

Request body

application/json

new_emailstring Required

The new email address to move the account to

Responses

application/json

  • dataMessageResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Rate limit

5 requests per 1mPer caller: the signed-in user for a bearer token; for an API key, the key and the end user's address when a backend forwards it, otherwise the client address

Returned object

MessageResponseDtoView all properties on this resource
Request
curl -X POST "https://auth.canopy-io.com/v1/auth/me/email" \
  -H "x-mfa-step-up-token: value" \
  -H "Content-Type: application/json" \
  -d '{
    "new_email": "string"
  }'
Response
{
  "data": {
    "message": "string"
  }
}
 Related endpoints
POSTRegister a new user
POSTCreate an additional Account for the authenticated admin (no new user)
GETReview the parked account-creation intent before resuming
POSTResume a deferred account creation parked at the register form
DELETEDismiss the parked account-creation intent without creating anything
POSTLook up invite details by token
POSTAccept an invite
POSTAuthenticate and receive tokens
POSTSelect an Account from a pre-auth session (multi-Account login)
POSTSwitch the active Application in an authenticated session
POSTRefresh access token
POSTLogout and revoke tokens
GETVerify email address
POSTResend verification email
POSTResend verification email by token
POSTRequest password reset
POSTReset password with token
POSTChange password (authenticated)
GETGet current user profile
GETGet current user avatar image
POSTUpload profile avatar
DELETERemove profile avatar
POSTConfirm an email-address change
GETGet current user permissions
GETList the Accounts the current user belongs to
GETList active sessions
DELETERevoke all sessions
DELETERevoke a specific session
 Was this page helpful?

Tell us how we can improve this guide.

Canopy