Appearance
Self-service API Reference
DELETE /me
Erase the current account
Use when a user requests irreversible account erasure. The password is rechecked; profile identifiers are anonymized, all credentials and sessions are removed, and the account is disabled.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| password | string | Yes |
json
{
"password": "CurrentAtLeastTwelve1"
}Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | invalid_credentials | invalid_credentials |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
GET /me
Get the current profile
Use from a signed-in user interface to display the authenticated user's profile. The identity is always taken from the user bearer subject; credentials and other users' data are never returned.
Responses
- 200 — Successful response
json
{
"created_at": "2026-01-01T00:00:00Z",
"display_name": "Alice Example",
"email": "alice@example.test",
"email_verified_at": "2026-01-01T00:00:00Z",
"id": "01J8Z3USER000000000000001",
"status": "active",
"username": "alice"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
PATCH /me
Update the current profile
Use when a user edits their own username or display name. Username is trimmed using the same rules as administrative user updates; email changes use the two-step email endpoints. At least one of username or display_name is required.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| display_name | string | No |
| username | string | No |
json
{
"display_name": "Alice Smith",
"username": "alice-new"
}Responses
- 200 — Successful response
json
{
"created_at": "2026-01-01T00:00:00Z",
"display_name": "Alice Smith",
"email": "alice@example.test",
"email_verified_at": "2026-01-01T00:00:00Z",
"id": "01J8Z3USER000000000000001",
"status": "active",
"username": "alice-new"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | at least one of username or display_name is required | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 409 | the resource already exists | Conflict |
| 422 | email change is not supported | Invalid Request; Invalid Request; Unsupported Field; Unsupported Field |
| 422 | unsupported_field | Invalid Request; Invalid Request; Unsupported Field; Unsupported Field |
| 422 | username is required | Invalid Request; Invalid Request; Unsupported Field; Unsupported Field |
| 422 | username must be a string | Invalid Request; Invalid Request; Unsupported Field; Unsupported Field |
| 500 | authentication service unavailable | Internal Server Error |
POST /me/email
Request an email change
Use when a user wants to replace their email. The current password is required; a single-use verification token is sent to the new address and the profile remains unchanged until confirmation.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| new_email | string | Yes |
| password | string | Yes |
json
{
"new_email": "alice.new@example.test",
"password": "CurrentAtLeastTwelve1"
}Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | invalid_credentials | invalid_credentials |
| 422 | email_taken | invalid_email; email_taken |
| 422 | invalid_email | invalid_email; email_taken |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /me/email/confirm
Confirm an email change
Use with the one-time token sent to the replacement address. The token is bound to the bearer subject; success updates email_verified_at and the email atomically.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| token | string | Yes |
json
{
"token": "email-change-token-from-email"
}Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 400 | invalid_token | invalid_token |
| 401 | authentication failed | Unauthorized |
| 500 | authentication service unavailable | Internal Server Error |
GET /me/export
Export current account data
Use to satisfy a data portability request. The response is an attachment containing profile, memberships, effective permissions, active sessions, and MFA/passkey counts; secrets and credential material are excluded.
Responses
- 200 — Successful response
json
{
"active_sessions": [
{
"created_at": "2026-01-01T00:00:00Z",
"expires_at": "2026-01-31T00:00:00Z",
"id": "8d7e5b3a0f6f4e1d..."
}
],
"effective_permissions": [
"orders:read:team"
],
"memberships": [
{
"group_id": "01J8Z3GROUP000000000000001",
"team_id": "01J8Z3TEAM000000000000001"
}
],
"passkey_count": 0,
"profile": {
"created_at": "2026-01-01T00:00:00Z",
"display_name": "Alice Example",
"email": "alice@example.test",
"email_verified_at": "2026-01-01T00:00:00Z",
"id": "01J8Z3USER000000000000001",
"status": "active",
"username": "alice"
},
"totp_enabled": false
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 500 | authentication service unavailable | Internal Server Error |
GET /me/passkeys
List own passkeys
Lists the current user's registered passkey identifiers in lexicographic order by canonical unpadded base64url credential ID. The exposed id is also the cursor key; malformed or noncanonical cursors return HTTP 400. Public keys and attestation data are never returned. See REST pagination for the shared collection contract.
Responses
- 200 — Successful response
json
{
"items": [
{
"created_at": "2026-01-01T00:00:00Z",
"id": "Y3JlZGVudGlhbC1pZA"
}
],
"next_cursor": ""
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | cursor must be a canonical unpadded base64url credential ID | Invalid Request; Invalid Request |
| 400 | limit must be a positive integer | Invalid Request; Invalid Request |
| 401 | authentication failed | Unauthorized |
| 500 | authentication service unavailable | Internal Server Error |
POST /me/passkeys/register/begin
Begin passkey registration
Use from a signed-in browser to add a WebAuthn credential. The browser passes the returned publicKey options to navigator.credentials.create; the ceremony expires after five minutes.
Responses
- 200 — Successful response
json
{
"publicKey": {
"attestation": "none",
"challenge": "base64url-challenge",
"pubKeyCredParams": [
{
"alg": -7,
"type": "public-key"
}
],
"rp": {
"id": "localhost",
"name": "teamusers"
},
"user": {
"displayName": "Alice Example",
"id": "base64url-user-handle",
"name": "alice"
}
}
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 500 | authentication service unavailable | Internal Server Error |
POST /me/passkeys/register/finish
Finish passkey registration
Use with the browser's PublicKeyCredential creation response. A valid response consumes the single-use challenge and stores only the credential material required for WebAuthn.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| id | string | Yes |
| rawId | string | Yes |
| response | object | Yes |
| type | string | Yes |
json
{
"id": "base64url-credential-id",
"rawId": "base64url-credential-id",
"response": {
"attestationObject": "base64url-attestation",
"clientDataJSON": "base64url-client-data"
},
"type": "public-key"
}Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 400 | invalid WebAuthn response | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 500 | authentication service unavailable | Internal Server Error |
DELETE /me/passkeys/{credID}
Delete one own passkey
Use to remove a passkey by its unpadded base64url credential ID. Unknown IDs return the same not-found problem regardless of ownership.
Path parameters
| Parameter | Description |
|---|---|
| credID | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 404 | the requested passkey was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
POST /me/password
Change the current password
Use when a signed-in user rotates their password. The current password is verified, the replacement must satisfy policy, and every refresh session (including the current one) is revoked. A first-login change_token from POST /auth/login is accepted as the bearer in place of an access token.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| current_password | string | Yes |
| new_password | string | Yes |
json
{
"current_password": "OldAtLeastTwelve1",
"new_password": "NewAtLeastTwelve2"
}Responses
- 200 — Successful response
json
{
"message": "password changed; all sessions were revoked; sign in again",
"sessions_revoked": true
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | invalid_credentials | invalid_credentials |
| 422 | weak_password | weak_password |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
GET /me/password-policy
Get the effective password policy
Use to display the password requirements currently resolved for the authenticated user. Only the merged policy is returned; the endpoint requires a user bearer.
Responses
- 200 — Successful response
json
{
"breach_check": true,
"history_count": 5,
"min_length": 12,
"require_digit": true,
"require_letter": true,
"require_lower": false,
"require_symbol": false,
"require_upper": false
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 500 | authentication service unavailable | Internal Server Error |
GET /me/permissions
List permission keys for display
Returns the authenticated user's flat list of unconditional permission keys from direct, group, and team-baseline role bindings; a baseline is included while the user has any unexpired group membership in that active team. The existing flat permissions string-array response contains neither per-grant team_id nor target-resource context, so treat it only as an informational/UI list, not authorization evidence or a final allow/deny result for any resource. It cannot resolve deny-overrides across every applicable platform and matching target-team grant for a specific resource. Bindings with non-empty ABAC conditions are omitted because no request-specific resource context is available; disabled users resolve to an empty permission list. For an authorization decision, use contextual POST /authz/check with the actual resource or evaluate v2 grants from GET /authz/permissions/{userID}?version=2 against the resource, including team_id.
Responses
- 200 — Successful response
json
{
"permissions": [
"docs:read:team",
"orders:read:own"
]
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | impersonation_forbidden | impersonation_forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
DELETE /me/totp
Disable TOTP
Use when a user removes MFA. Submit a current TOTP code or unused backup code; active TOTP, pending TOTP, and backup credentials are deleted.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| code | string | Yes |
json
{
"code": "123456"
}Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 500 | authentication service unavailable | Internal Server Error |
POST /me/totp/backup-codes
Regenerate TOTP backup codes
Use when backup codes are exhausted or suspected exposed. The current password and an active TOTP enrollment are required; old codes are replaced atomically.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| password | string | Yes |
json
{
"password": "CurrentAtLeastTwelve1"
}Responses
- 200 — Successful response
json
{
"backup_codes": [
"abcd-1234-efgh-5678",
"9ijk-lmno-0123-pqrs",
"1111-2222-3333-4444"
]
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | invalid_credentials | invalid_credentials |
| 404 | mfa_not_enrolled | mfa_not_enrolled |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /me/totp/confirm
Confirm TOTP enrollment
Use after scanning the enrollment QR code. Submit the current six-digit code; the pending secret becomes active and ten one-time backup codes are returned.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| code | string | Yes |
json
{
"code": "123456"
}Responses
- 200 — Successful response
json
{
"backup_codes": [
"abcd-1234-efgh-5678",
"9ijk-lmno-0123-pqrs",
"1111-2222-3333-4444"
]
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 409 | totp_already_enabled | totp_already_enabled |
| 500 | authentication service unavailable | Internal Server Error |
POST /me/totp/enroll
Start TOTP enrollment
Use in security settings to start MFA enrollment. The returned secret and otpauth URL are displayed once; the credential remains pending until a code is confirmed.
Responses
- 200 — Successful response
json
{
"otpauth_url": "otpauth://totp/teamusers:alice?secret=JBSWY3DPEHPK3PXP&issuer=teamusers",
"secret": "JBSWY3DPEHPK3PXP"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 409 | totp_already_enabled | totp_already_enabled |
| 500 | authentication service unavailable | Internal Server Error |