Users — Core API

Lists all users belonging to an issuer with pagination.

Users are identities within your issuer. Each user has credentials (verifiers), profile data, and can belong to organizations.

User statuses:

• active - Normal operational state, can authenticate
• suspended - Temporarily blocked from authentication (admin action)
• disabled - Permanently blocked but data retained
• deleted - Soft deleted, scheduled for permanent removal

Privacy note: The list endpoint returns hashed usernames for privacy. Use the Get User endpoint to retrieve full user details including the actual username.

Data residency: Users may be stored in different geographic regions based on your issuer's identity store configuration. The region field indicates where each user's data resides.

Creates a new user within an issuer.

Use this endpoint to programmatically create user accounts. This is useful for:

• Migrating users from another system
• Creating users via admin tools or back-office applications
• Setting up test accounts

Authentication methods: After creating a user, add authentication methods (verifiers) using the Create User Verifier endpoint. Users cannot log in until they have at least one verifier configured.

Email verification: Users created via this API are not email-verified by default. Set email_verified: true in the request if you've verified the email through your own process.

Data placement: Use placement.region to require one of wnam, enam, sam, apac, oc, me, weur, or eeur. Use placement.jurisdiction: "eu" to require an EU store. When both are supplied, both constraints must match. An unavailable or full explicit placement returns 400 and never falls back. Without placement, routing follows the API caller's geography as a best-effort preference; this is usually the operator or migration host, not the end user.

Organization membership: To add users to organizations, use the Add Organization Member endpoint after user creation.

Retrieves the full profile of a user by their ID.

This endpoint returns complete user information including:

• Profile data - Username, email, name, and custom metadata
• Status - Current account status and any restrictions
• Timestamps - Creation, last update, and last login times
• Organization memberships - Groups the user belongs to

Note: Sensitive data like password hashes and passkey credentials are never returned. Use the List User Verifiers endpoint to see which authentication methods are configured.

Updates a user's profile information.

All fields in the request body are optional - only include the fields you want to change.

Updatable fields:

• Profile data - Name, email, phone, custom metadata
• Status - Suspend, disable, or reactivate users
• Preferences - Locale, timezone, notification settings

Important notes:

• Changing the username/email may require re-verification depending on issuer settings
• Suspending a user immediately invalidates all active sessions
• Custom metadata is merged with existing metadata (use null to remove a key)

To change authentication methods: Use the verifier endpoints instead - this endpoint only updates profile data, not passwords or passkeys.

Initiates user deletion (async).

This starts an asynchronous deletion workflow that:

1. Marks user as pending_deletion - User cannot log in or be modified
2. Revokes all sessions - Active sessions are invalidated
3. Revokes personal tokens - All API tokens for the user are revoked
4. Cleans up data - User data is removed from all indexes

Tracking deletion progress:

• Use GET /users/{user_id} to check the user's status
• Status will be pending_deletion until deletion completes
• Once complete, the user endpoint returns 404

During pending deletion:

• User cannot authenticate
• User data cannot be modified
• User will not appear in list results (unless filtered by status=pending_deletion)

Idempotency:

• Calling delete on a user already pending deletion is safe and returns 202

GDPR/Privacy considerations:

• This satisfies "right to erasure" requests
• Audit logs are retained separately for compliance purposes

Lists all authentication methods (verifiers) configured for a user.

Verifiers are the credentials users use to authenticate. Each user can have multiple verifiers of different types.

Verifier types:

• password - Traditional password authentication
• passkey - WebAuthn/FIDO2 passkeys (biometric or security key)
• totp - Time-based one-time passwords (authenticator apps)
• backup_codes - Recovery codes for MFA
• magic_link - Email-based passwordless authentication
• oauth - Linked social/OAuth provider account

Security note: Sensitive credential data (password hashes, TOTP secrets, passkey private keys) is never returned. Only metadata like verifier type, creation date, and last-used timestamp are included.

Adds a new authentication method (verifier) for a user.

Use this endpoint to configure how a user can authenticate. This is required after creating a user via the API, as users cannot log in without at least one verifier.

Verifier types:

• password - Set a password for the user. The password is hashed securely (Argon2) before storage.
• passkey - Register a WebAuthn credential. Requires the credential public key from the registration ceremony.
• backup_codes - Generate recovery codes for MFA fallback.
• totp_enrollment - Start TOTP enrollment (returns secret and QR code URI for authenticator apps)

Password requirements: Password strength requirements are configured at the issuer level. The API will reject passwords that don't meet the configured policy.

TOTP Enrollment Flow:

1. POST this endpoint with type: "totp_enrollment" and issuer_name
2. Response includes enrollment_id, secret, and provisioning_uri for QR code
3. User scans QR code with their authenticator app
4. Complete enrollment via POST /verifiers/complete-enrollment with the enrollment_id and TOTP code

Important: For passkey registration, you typically need to:

1. Initiate a WebAuthn registration ceremony on the client
2. Send the resulting credential to this endpoint

Consider using the hosted passkey registration flow instead for a simpler integration.

Retrieves details for a specific verifier.

Returns verifier metadata including type, status, and usage information.

Security note: Sensitive credential data is never returned.

Updates a verifier's metadata or status.

Updatable fields:

• status - Change verifier status (active, disabled, revoked)
• name - User-friendly name for the verifier
• description - Description text
• metadata - Custom metadata

Note: To regenerate backup codes, use the dedicated regenerate endpoint.

Deletes an authentication method (verifier) from a user.

This performs a soft delete by default, setting the verifier status to "revoked". The verifier data is retained for audit purposes but cannot be used for authentication.

Warning: Ensure the user has at least one other active verifier before deleting, otherwise they may be locked out of their account.

Security note: Deleting the last active verifier will prevent the user from authenticating.

Regenerates backup codes for a backup_codes verifier.

This invalidates all existing codes and generates new ones.

Important:

• All existing codes are invalidated immediately
• Store the new codes securely - they cannot be retrieved again
• The response includes the plaintext codes only once

Verifies a TOTP code or backup code for a user's verifier.

For TOTP verifiers:

• Submit a 6-digit code from the user's authenticator app
• Codes are time-based and valid for a short window (typically 30 seconds)

For backup_codes verifiers:

• Submit one of the user's backup codes
• The code is consumed upon successful verification and cannot be reused
• The response includes the count of remaining backup codes

Rate limiting: Too many failed attempts will temporarily lock the account.

Completes the enrollment process for a multi-step verifier.

TOTP Enrollment: Submit the enrollment_id from POST /verifiers (with type: totp_enrollment) along with a valid 6-digit TOTP code from the user's authenticator app.

Options:

• generate_backup_codes - If true, generates and returns backup codes along with the verifier

On success:

• The TOTP verifier is activated and can be used for authentication
• If backup codes were requested, they are included in the response (store securely - shown only once)

On failure:

• Returns an error indicating the code was invalid or enrollment expired
• User must restart the enrollment process by calling POST /verifiers again

Lists all trusted devices for a user.

Trusted devices are devices that have been marked as trusted for MFA skip. When a user authenticates from a trusted device, they may bypass MFA challenges based on issuer policy.

Response includes:

• Device ID and fingerprint
• Device name (if provided during trust)
• User agent string
• Trust and expiration timestamps
• Last used timestamp

Marks a device as trusted for MFA skip.

When a device is trusted, subsequent authentications from this device may bypass MFA challenges based on issuer policy.

Required fields:

• fingerprint - Unique device identifier (alphanumeric, hyphens, underscores, dots allowed)

Optional fields:

• name - User-friendly device name (e.g., "My MacBook Pro")
• user_agent - Browser/client user agent string
• duration_days - Trust duration in days (1-365, default: 30)

Security considerations:

• Trusted devices should only be marked on user request
• The fingerprint should be cryptographically generated
• Trust expires automatically after the specified duration

Revokes trust for a specific device.

After revocation, the user will be required to complete MFA when authenticating from this device (based on issuer policy).

Note: This operation is idempotent - revoking a non-existent or already-revoked device returns success.

Revokes trust for all of a user's devices.

This is useful for security-related actions such as:

• User reports account compromise
• Admin security audit
• User requests to clear all trusted devices

After this operation, the user will be required to complete MFA on all subsequent authentications (based on issuer policy).