> Markdown version of https://authpi.com/docs/reference/core-api/users/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Users — AuthPI Core API

User management endpoints. Users are identities within an Issuer. Each user has a profile, authentication verifiers (passwords, passkeys), and can belong to Organizations.

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/users

**List Users**

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.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional | Maximum number of items to return (1-100, default: 50) |
| `cursor` | string | Optional | Pagination cursor (user_id from previous response) |
| `status` | active \| suspended \| disabled \| deleted | Optional | Filter by user status |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Paginated list of users | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/users

**Create User**

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.

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

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `username_type` | email \| phone \| unique | Required |  |
| `username` | string | Required |  |
| `profile` | object | Optional |  |
| `scopes` | string[] | Optional |  |
| `security` | object | Optional |  |
| `compliance` | object | Optional |  |
| `preferences` | object | Optional |  |
| `custom_fields` | object | Optional |  |
| `metadata` | object | Optional |  |
| `requires_approval` | boolean | Optional |  |
| `signup_reason` | string | Optional |  |
| `triggered_rule` | string | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | User created successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 409 | **Conflict** - The request conflicts with the current state of the resource. | `ApiError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}

**Get User**

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.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | User profile retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## PATCH /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}

**Update User**

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.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | active \| suspended \| blocked | Optional |  |
| `status_at` | integer | Optional | Unix timestamp in milliseconds |
| `status_reason` | string \| null | Optional |  |
| `status_by` | string | Optional |  |
| `username_type` | email \| phone \| unique | Optional |  |
| `username` | string | Optional |  |
| `profile` | object | Optional |  |
| `scopes` | string[] | Optional |  |
| `security` | object | Optional |  |
| `compliance` | object | Optional |  |
| `preferences` | object | Optional |  |
| `approval` | object | Optional |  |
| `custom_fields` | object | Optional |  |
| `metadata` | Metadata | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | User updated successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |

## DELETE /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}

**Delete User**

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

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 202 | Deletion accepted and processing | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}/verifiers

**List User Verifiers**

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.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Verifiers retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}/verifiers

**Create User Verifier**

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.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |

### Request body

Content type: `application/json`

One of (variant 1):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | Required |  |
| `description` | string \| null | Optional |  |
| `metadata` | Metadata | Optional |  |
| `type` | password | Required |  |
| `password` | string | Required |  |
| `must_change` | boolean | Optional |  |
| `expires_at` | integer | Optional | Unix timestamp in milliseconds |

One of (variant 2):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | Required |  |
| `description` | string \| null | Optional |  |
| `metadata` | Metadata | Optional |  |
| `type` | temporary_password | Required |  |
| `password` | string | Required |  |
| `expires_at` | integer | Required | Unix timestamp in milliseconds |
| `created_by` | string | Optional |  |

One of (variant 3):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | Required |  |
| `description` | string \| null | Optional |  |
| `metadata` | Metadata | Optional |  |
| `type` | passkey | Required |  |
| `credential` | object | Required |  |

One of (variant 4):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | Required |  |
| `description` | string \| null | Optional |  |
| `metadata` | Metadata | Optional |  |
| `type` | totp | Required |  |
| `secret` | string | Required |  |
| `algorithm` | SHA1 \| SHA256 \| SHA512 | Optional |  |
| `digits` | integer | Optional |  |
| `period` | integer | Optional |  |
| `verification_code` | string | Required |  |

One of (variant 5):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | Required |  |
| `description` | string \| null | Optional |  |
| `metadata` | Metadata | Optional |  |
| `type` | totp_enrollment | Required |  |
| `issuer_name` | string | Required | Name shown in authenticator apps |

One of (variant 6):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | Required |  |
| `description` | string \| null | Optional |  |
| `metadata` | Metadata | Optional |  |
| `type` | backup_codes | Required |  |
| `codes` | string[] | Required |  |

One of (variant 7):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | Required |  |
| `description` | string \| null | Optional |  |
| `metadata` | Metadata | Optional |  |
| `type` | sms_otp | Required |  |
| `phone_number` | string | Required |  |
| `verification_code` | string | Required |  |

One of (variant 8):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | Required |  |
| `description` | string \| null | Optional |  |
| `metadata` | Metadata | Optional |  |
| `type` | email_otp | Required |  |
| `email` | string | Required |  |
| `verification_code` | string | Required |  |

One of (variant 9):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | Required |  |
| `description` | string \| null | Optional |  |
| `metadata` | Metadata | Optional |  |
| `type` | email_link | Required |  |
| `credential` | object | Required |  |

One of (variant 10):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | Required |  |
| `description` | string \| null | Optional |  |
| `metadata` | Metadata | Optional |  |
| `type` | oauth2 | Required |  |
| `provider` | string | Required |  |
| `provider_user_id` | string | Required |  |
| `email` | string | Optional |  |
| `profile_url` | string | Optional |  |
| `has_refresh_token` | boolean | Optional |  |

One of (variant 11):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | Required |  |
| `description` | string \| null | Optional |  |
| `metadata` | Metadata | Optional |  |
| `type` | wallet | Required |  |
| `address` | string | Required | Blockchain address |
| `network` | string | Required | CAIP-2 network identifier |


### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | TOTP enrollment started (for type: totp_enrollment) | `object` |
| 201 | Verifier created successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}/verifiers/{verifier_id}

**Get User Verifier**

Retrieves details for a specific verifier.

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

**Security note:** Sensitive credential data is never returned.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |
| `verifier_id` | string | Required | The unique identifier of the verifier |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Verifier retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## PATCH /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}/verifiers/{verifier_id}

**Update User Verifier**

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.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |
| `verifier_id` | string | Required | The unique identifier of the verifier |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | active \| disabled \| revoked | Optional |  |
| `name` | string \| null | Optional |  |
| `description` | string \| null | Optional |  |
| `metadata` | Metadata | Optional |  |
| `must_change` | boolean | Optional |  |
| `last_used` | object | Optional |  |
| `usage_count` | integer | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Verifier updated successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## DELETE /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}/verifiers/{verifier_id}

**Delete User Verifier**

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.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |
| `verifier_id` | string | Required | The unique identifier of the verifier |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 204 | **No Content** - The operation completed successfully with no response body. | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}/verifiers/{verifier_id}/regenerate

**Regenerate Backup Codes**

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

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |
| `verifier_id` | string | Required | The unique identifier of the verifier |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Backup codes regenerated successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}/verifiers/{verifier_id}/verify

**Verify Authentication Code**

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.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |
| `verifier_id` | string | Required | The unique identifier of the verifier |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | Required | TOTP code (6 digits) or backup code |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Verification result | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}/verifiers/complete-enrollment

**Complete Verifier Enrollment**

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

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `enrollment_id` | string | Required |  |
| `code` | string | Required | 6-digit TOTP code from authenticator |
| `generate_backup_codes` | boolean | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Enrollment completion result | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}/trusted-devices

**List Trusted Devices**

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

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Trusted devices retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}/trusted-devices

**Trust a Device**

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

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `fingerprint` | string | Required |  |
| `name` | string | Optional |  |
| `user_agent` | string | Optional |  |
| `duration_days` | integer | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Device trusted successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## DELETE /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}/trusted-devices/{device_id}

**Revoke Trusted Device**

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.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |
| `device_id` | string | Required | The unique identifier of the trusted device |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 204 | **No Content** - The operation completed successfully with no response body. | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}/trusted-devices/revoke-all

**Revoke All Trusted Devices**

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

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | All devices revoked successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |