Account API at a glance
What the account API under /v1/me is for, who may call it, how it authenticates and what it refuses, before you read the route-by-route reference.
On this page
The account API is the JSON twin of the account area: everything a person can do on their own account, as requests. It lives under /v1/me. The page API lists every route with its request and response shapes; this page explains the rules that apply to all of them.
An application that only needs to know who signed in does not use this API. It uses the OIDC endpoints and the SDK: see Build with identity.
What it covers#
The routes are grouped by what they manage. Each group is a page of the account area, described in Your account.
| Group | What it does |
|---|---|
| Profile, avatar, emails | Read and change the profile and picture; add, verify, remove addresses and choose the primary one. |
| Sign-in methods | Passkeys, password, authenticator app, recovery codes, linked accounts, and the optional extra sign-in steps. |
| Sessions and devices | List sessions (with the single sign-on connection a session is pinned to, where it has one), end one or all, list devices, trust or untrust them, sign out. |
| Step-up | Confirm it is you with a passkey, an authenticator code, a linked provider or, on a session opened with a passkey or a provider that asserted multi-factor, the account password. |
| Apps and access | List and revoke the consents given to applications, and list and revoke the agents that act for you. |
| Organizations and invitations | List memberships with their kind, parent, sponsor and domain, leave one, list the invitations addressed to a verified address of yours, accept or decline one, and read and answer an emailed invitation. |
| Data | Request and download an export; deactivate or delete the account. |
| Notifications and activity | Notification settings, security events, the activity list, the security checkup and the overview. |
| Developer | Personal access tokens, and registering and managing a client of your own where your organization allows it. |
Who may call it#
There are three kinds of caller, and they are not equal.
| Caller | What it may reach |
|---|---|
| A signed-in browser | The whole API, from the identity site itself. The browser sends its session cookie, and every request that changes something must come from the identity site. A request from another site is refused with cross_origin. Cross-origin browser access is not offered. |
| A first-party application with an access token | The whole API, with a token that is bound to a person's live session. |
| A personal access token | The profile only: GET and PATCH on /v1/me, with the scopes identity.self.profile.read and identity.self.profile.write. The older identity.self.read and identity.self.write also work. Behind the pat_bearer_api feature flag, which defaults OFF, and available only where your organization allows it. See Scopes. |
A third-party application's access token can read the profile with the profile scope but cannot change anything: writes need a token issued to a first-party client. A request that presents both a cookie and an Authorization header is refused.
How a request is checked#
- Authenticate. A token must be a valid, sender-constrained access token for a human, with a live session behind it. See DPoP.
- Assurance for sensitive routes. Changing how you sign in, exporting data, creating tokens and similar actions need a session at assurance level 2 or above, confirmed in the last 30 minutes (an operator can shorten that window). A session that signed in through an organization's single sign-on connection needs a step-up made on this session with a method of your own, because the provider controls what that sign-in asserts. If it is not, the answer is
step_up_required(401), listing the methods you can answer with. Prove one with the step-up routes, then repeat the request. - A new browser waits. A few changes are open to a session without a second factor, for example adding an email address or turning on an extra sign-in step. They are allowed only from a browser the account has already known for a while, and a browser becomes known only through a sign-in that proved more than the password. From a newer browser an account with no second factor gets
device_too_new; an account that holds a passkey or an authenticator app getsstep_up_requiredinstead, because confirming that factor is the way through. - Limits. A route can answer 429 with
Retry-After.
An account that an organization manages cannot change its own sign-in methods, create personal access tokens or deactivate itself: those routes answer managed_account (403), because the credentials and lifecycle belong to the organization. A step-up that such an account has nothing to answer gets the same answer, in place of a step_up_required it could never satisfy.
A session opened with the emailed code that replaces a lost passkey, or with "Continue with my password only (limited session)", has not used a second factor: a route that allows an unseasoned session through on the age of its browser answers step_up_required for it, and only a confirmed second factor passes.
A recovery code alone does not unlock the two actions that need a live authenticator proof: regenerating recovery codes and removing the authenticator app.
What an answer looks like#
- A browser gets
{ "error": { "code", "reason", "message", "requestId" } }(reasononly when the cause is safe to say, for exampleaddress_cappedorpasskey_limit), plusmethodsandproviderson a step-up answer andretryAfterSon a limit. - A token caller gets
{ "error", "error_description" }(and the samereasonwhere one applies) with the RFC 6750 challenge headers. - Successful answers are marked
no-store. A DPoP request also gets a freshDPoP-Nonce.
The statuses are on HTTP status codes and Retry-After, and the text of each code is on Error codes.
What it deliberately does not do#
- It does not return secrets: no password, no recovery codes after the one time they are shown, no token after it is created.
- It does not tell you whether an address has an account.
- It does not offer roles or permissions. Those come from the authorization service; see Authorization.