GET /v1/users

users:read

List users, cursor-paginated.

GET /v1/users/:id

users:read

Fetch a single user. Never includes private_metadata.

PATCH /v1/users/:id

users:write

✓

Update a user profile or metadata.

POST /v1/users/:id/ban

users:write

✓

Ban a user and revoke every session.

DELETE /v1/users/:id

users:delete

✓

Soft-delete a user; PII is scrubbed after 30 days.

POST /v1/users

users:write

✓

Create a user from an email and optional password, name and metadata. Emits user.created.

POST /v1/users/:id/unban

users:write

✓

Lift a ban. Sessions are not restored.

POST /v1/users/:id/lock

users:write

✓

Lock an account so it cannot sign in, for an optional duration (default one year).

POST /v1/users/:id/unlock

users:write

✓

Clear a lockout so the account can sign in again.

POST /v1/users/:id/reset_mfa

users:write

✓

Remove every second factor and its recovery codes.

DELETE /v1/users/:id/mfa/:factorId

users:write

✓

Remove one second factor. The last factor removed also turns MFA off.

PUT /v1/users/:id/metadata

users:write

✓

Replace the metadata bags wholesale. Each bag present overwrites the stored one.

GET /v1/users/:id/sessions

users:read

List a user's active sessions.

POST /v1/users/:id/sessions/revoke

users:write

✓

Revoke every session a user holds and bump sessions_version.

POST /v1/users/:id/email_addresses

users:write

✓

Add an email address to a user. Starts unverified.

POST /v1/users/:id/email_addresses/:eid/verify

users:write

✓

Mark an address verified on the backend authority, no code round-trip.

POST /v1/users/:id/email_addresses/:eid/primary

users:write

✓

Make a verified address primary. Unverified addresses are refused.

GET /v1/users/:id/identities

users:read

List a user's linked identities: their Atlas email/password identity plus each linked external/OAuth provider account. No tokens.

POST /v1/users/:id/external_accounts/connect

users:write

Backend-initiated connect: start an OAuth flow that links a NEW provider identity to this user (the caller supplies the user id). Returns an authorization_url to redirect the browser to; the callback links the provider without minting a session. Refuses an identity already owned by another user (IDENTITY_ALREADY_LINKED).

POST /v1/users/:id/identities

users:write

✓

Merge a secondary user into this primary: moves the secondary's provider accounts and verified identifiers over (skipping collisions), re-points org memberships without escalating role, revokes the secondary's sessions and retires it. Never clears the primary's MFA or ban.

DELETE /v1/users/:id/identities/:identityId

users:write

✓

Unlink a provider identity, extracting it into a new standalone user (Auth0 semantics). The sole/primary identity cannot be unlinked.

GET /v1/users/:id/grants

grants:read

List the OAuth clients a user has authorized, with the granted scopes and grant time. Never returns tokens.

DELETE /v1/users/:id/grants

grants:write

✓

Revoke every consent grant a user holds and cascade-revoke all associated tokens through the standard revocation path.

GET /v1/users/:id/oauth_access_tokens/:provider

oauth_tokens:read

Fetch a stored provider token, refreshing it single-flight if stale.