Account management (me)

The me surface lets a signed-in user manage their own account. It requires the user's session (or a personal access token) — never a secret key. Build a custom account UI on these, or use @atlas/react's <UserProfile /> and hooks.

Profile

GET   /v1/client/me                → the user with emails, linked accounts, passkeys
PATCH /v1/client/me                → update profile + unsafe_metadata (public_metadata refused)
POST  /v1/client/me/avatar         → upload avatar (raw image bytes as the body)
POST  /v1/client/me/change_password→ verify current, apply policy, revoke other sessions
POST  /v1/client/me/set_password   → set a first password (OAuth-only / guest account)
POST  /v1/client/me/reauthenticate → step-up re-auth to refresh the step-up window in place

Email addresses & identities

POST   /v1/client/me/email_addresses                         → add an address (sends a code)
POST   /v1/client/me/email_addresses/:id/attempt_verification→ verify with the code
POST   /v1/client/me/email_addresses/:id/primary             → make a verified address primary
DELETE /v1/client/me/email_addresses/:id                     → remove (last verified one refused)

POST   /v1/client/me/external_accounts/connect               → link a new provider ("Connect GitHub")
POST   /v1/client/me/external_accounts/:id/reauthorize       → request additional scopes
POST   /v1/client/me/external_accounts/:id/revoke            → revoke the stored provider token (keep the link)
DELETE /v1/client/me/external_accounts/:id                   → unlink (removing the only sign-in method refused)
GET    /v1/client/me/external_accounts/:provider/token       → the user's own provider token (refreshed if stale)

Multi-factor

GET    /v1/client/me/mfa                     → list factors (never secrets)
POST   /v1/client/me/mfa/totp                → begin authenticator enrollment (secret shown once)
POST   /v1/client/me/mfa/totp/:id/verify     → confirm; receive recovery codes once
POST   /v1/client/me/mfa/sms                 → enroll a phone as SMS second factor
POST   /v1/client/me/mfa/sms/:id/verify      → confirm SMS enrollment
POST   /v1/client/me/mfa/push                → register a device for push MFA (number-matching)
POST   /v1/client/me/mfa/backup_codes        → issue a fresh set of recovery codes
DELETE /v1/client/me/mfa/:id                 → remove a factor (last one also drops recovery codes)

GET    /v1/client/me/passkeys                → list passkeys
POST   /v1/client/me/passkeys/begin | /finish→ register a passkey (WebAuthn)
GET    /v1/client/me/trusted_devices         → browsers trusted to skip 2FA

Organizations (from the user's side)

GET  /v1/client/me/organizations               → the user's memberships
GET  /v1/client/me/organization_suggestions     → orgs discoverable via verified email domain
POST /v1/client/me/organization_membership_requests → request to join a matching org
POST /v1/client/organizations                    → create an org (if the instance allows it)
POST /v1/client/organization_invitations/:invitationId/accept → accept an invitation

Managing an active org (invite, update, list members) requires the relevant org:sys_* permission — see Roles & permissions.

Privacy (GDPR self-service)

POST /v1/client/me/data_export        → request an export of your own data (async job)
GET  /v1/client/me/data_export/:id    → the produced package once ready (no secrets/hashes)
POST /v1/client/me/deletion_request   → request account erasure (grace/cancellation window)
POST /v1/client/me/deletion_request/:id/cancel → cancel within the window

Example

import { UserProfile, useUser } from '@atlas/react';

// Prebuilt UI
<UserProfile />;

// Or read the user directly
const { user } = useUser();
console.log(user?.primaryEmailAddress, user?.publicMetadata);