Skip to content

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) ​

FieldTypeRequired
passwordstringYes
json
{
  "password": "CurrentAtLeastTwelve1"
}

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401invalid_credentialsinvalid_credentials
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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 ​

StatusCodeDetail
401authentication failedUnauthorized
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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) ​

FieldTypeRequired
display_namestringNo
usernamestringNo
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 ​

StatusCodeDetail
400at least one of username or display_name is requiredInvalid Request
401authentication failedUnauthorized
409the resource already existsConflict
422email change is not supportedInvalid Request; Invalid Request; Unsupported Field; Unsupported Field
422unsupported_fieldInvalid Request; Invalid Request; Unsupported Field; Unsupported Field
422username is requiredInvalid Request; Invalid Request; Unsupported Field; Unsupported Field
422username must be a stringInvalid Request; Invalid Request; Unsupported Field; Unsupported Field
500authentication service unavailableInternal 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) ​

FieldTypeRequired
new_emailstringYes
passwordstringYes
json
{
  "new_email": "alice.new@example.test",
  "password": "CurrentAtLeastTwelve1"
}

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401invalid_credentialsinvalid_credentials
422email_takeninvalid_email; email_taken
422invalid_emailinvalid_email; email_taken
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
tokenstringYes
json
{
  "token": "email-change-token-from-email"
}

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
400invalid_tokeninvalid_token
401authentication failedUnauthorized
500authentication service unavailableInternal 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 ​

StatusCodeDetail
401authentication failedUnauthorized
500authentication service unavailableInternal 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 ​

StatusCodeDetail
400cursor must be a canonical unpadded base64url credential IDInvalid Request; Invalid Request
400limit must be a positive integerInvalid Request; Invalid Request
401authentication failedUnauthorized
500authentication service unavailableInternal 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 ​

StatusCodeDetail
401authentication failedUnauthorized
500authentication service unavailableInternal 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) ​

FieldTypeRequired
idstringYes
rawIdstringYes
responseobjectYes
typestringYes
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 ​

StatusCodeDetail
400invalid WebAuthn responseInvalid Request
401authentication failedUnauthorized
500authentication service unavailableInternal 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 ​

ParameterDescription
credIDPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
404the requested passkey was not foundNot Found
500authentication service unavailableInternal 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) ​

FieldTypeRequired
current_passwordstringYes
new_passwordstringYes
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 ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401invalid_credentialsinvalid_credentials
422weak_passwordweak_password
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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 ​

StatusCodeDetail
401authentication failedUnauthorized
500authentication service unavailableInternal 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 ​

StatusCodeDetail
401authentication failedUnauthorized
403impersonation_forbiddenimpersonation_forbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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) ​

FieldTypeRequired
codestringYes
json
{
  "code": "123456"
}

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
500authentication service unavailableInternal 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) ​

FieldTypeRequired
passwordstringYes
json
{
  "password": "CurrentAtLeastTwelve1"
}

Responses ​

  • 200 — Successful response
json
{
  "backup_codes": [
    "abcd-1234-efgh-5678",
    "9ijk-lmno-0123-pqrs",
    "1111-2222-3333-4444"
  ]
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401invalid_credentialsinvalid_credentials
404mfa_not_enrolledmfa_not_enrolled
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
codestringYes
json
{
  "code": "123456"
}

Responses ​

  • 200 — Successful response
json
{
  "backup_codes": [
    "abcd-1234-efgh-5678",
    "9ijk-lmno-0123-pqrs",
    "1111-2222-3333-4444"
  ]
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
409totp_already_enabledtotp_already_enabled
500authentication service unavailableInternal 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 ​

StatusCodeDetail
401authentication failedUnauthorized
409totp_already_enabledtotp_already_enabled
500authentication service unavailableInternal Server Error