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

# Issuers — AuthPI Core API

Issuer management endpoints. An Issuer is your identity provider—it controls authentication methods, signup policies, session settings, and contains its own isolated user pool.

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

**List Issuers**

Lists all issuers belonging to an account with pagination.

Returns issuers in descending order by creation date (newest first). Use this endpoint to:

- View all identity providers in your account
- Monitor issuer status across environments (production, staging)
- Get issuer IDs for subsequent API calls

**Tip:** Most accounts have one issuer per environment (e.g., production, staging). If you need users to have a single identity across multiple applications, use one issuer with multiple clients instead of multiple issuers.

### Path parameters

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

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional | Maximum number of items to return (1-100, default: 50) |
| `cursor` | string | Optional | Pagination cursor (issuer ID from previous response) |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Paginated list of issuers | `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

**Create Issuer**

Creates a new Issuer within an account.

An Issuer is your identity provider in AuthPI. Each issuer maintains an isolated user pool and can be configured with:

- **Authentication methods** - Enable password, magic links, OAuth/social login, or passkeys
- **Signup policies** - Control who can register (open, invite-only, domain restrictions)
- **Session settings** - Configure token lifetimes, idle timeouts, and device fingerprinting
- **Branding** - Customize hosted login pages with your logo and colors

**Common patterns:**
- **One issuer per environment** - Create separate issuers for production, staging, and development
- **One issuer per application** - If applications require separate user bases
- **Shared issuer** - Multiple applications sharing one user pool (use multiple clients within one issuer)

After creating an issuer, you'll need to create at least one OAuth Client to authenticate users.

### Path parameters

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

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `description` | string \| null | Optional | A description for the resource. Markdown supported. |
| `links` | object | Optional |  |
| `available_scopes` | string[] | Optional |  |
| `status` | active \| disabled \| suspended \| deleted | Optional |  |
| `settings` | object | Optional |  |
| `metadata` | object | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Issuer 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` |

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

**Get Issuer**

Retrieves the full configuration of an issuer by its ID.

An Issuer is your identity provider within AuthPI. This endpoint returns all issuer settings including:

- **Authentication methods** - Configured login methods (password, magic links, OAuth, passkeys)
- **Signup policies** - Email verification, domain restrictions, admin approval settings
- **Session settings** - Lifetimes, idle timeouts, device fingerprinting
- **Security policies** - Redirect URI rules, CORS origins, token settings
- **Branding** - Display name, logo, theme colors for hosted login pages

Use this endpoint to inspect issuer configuration or verify settings after updates.

### 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 |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Issuer configuration retrieved 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` |
| 409 | **Conflict** - The request conflicts with the current state of the resource. | `ApiError` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |
| 422 | **Unprocessable Entity** - The request is well-formed but contains semantic errors. | `ApiError` |
| 429 | **Too Many Requests** - Rate limit or resource limit exceeded. | `ApiError` |
| 500 | **Internal Server Error** - An unexpected error occurred. | `ApiError` |

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

**Update Issuer**

Updates an issuer's configuration.

Use this endpoint to modify any issuer setting. All fields in the request body are optional - only include the fields you want to change.

**Configurable settings include:**
- **Authentication methods** - Add/remove login methods, configure MFA requirements
- **Signup policies** - Change registration mode, update domain restrictions
- **Session settings** - Adjust token lifetimes, enable/disable features
- **Branding** - Update display name, logo, or theme colors
- **Security policies** - Modify redirect URI rules, CORS origins

**Important:** Some changes may affect active users:
- Disabling an authentication method won't log out users, but they can't use that method next login
- Reducing session lifetime affects new sessions only, not existing ones
- Changing signup policies takes effect immediately for new registrations

### 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 |
| --- | --- | --- | --- |
| `name` | string | Optional | A name for the resource. |
| `description` | string | Optional |  |
| `links` | object | Optional |  |
| `available_scopes` | string[] | Optional |  |
| `status` | active \| disabled \| suspended \| deleted | Optional |  |
| `settings` | object | Optional |  |
| `metadata` | Metadata | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Issuer 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}

**Delete Issuer**

Deletes an issuer (soft delete).

This performs a soft delete - the issuer is marked as deleted but data is retained for a grace period. During this period:

- **Users cannot authenticate** - All login attempts will fail
- **API access is blocked** - Calls to this issuer's endpoints return 404
- **Data is preserved** - User data, sessions, and audit logs are retained
- **Recovery is possible** - Contact support to restore within the grace period

**Before deleting:**
1. Ensure no production applications depend on this issuer
2. Migrate users if needed (export user data first)
3. Revoke any active sessions to log out users immediately

**After deletion:**
- Associated OAuth clients are also soft-deleted
- Webhook subscriptions are deactivated
- User data is scheduled for permanent deletion after the grace period

### 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 |

### 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` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/auth-methods

**List Auth Methods**

Lists all authentication methods configured for an issuer.

Authentication methods define how users can sign in to your application. Each method can be enabled or disabled for login and signup independently.

**Method types include:**
- **password** - Traditional username/password authentication
- **email_link** - Passwordless magic links sent via email
- **email_otp** - One-time passwords sent via email
- **passkey** - WebAuthn/FIDO2 biometric and security key authentication
- **totp** - Time-based one-time passwords (authenticator apps)
- **oidc** - OpenID Connect providers (Google, Microsoft, etc.)
- **oauth2** - Generic OAuth 2.0 providers
- **apple** - Sign in with Apple
- **github** - GitHub OAuth

Each method has its own settings specific to that authentication type.

### 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 |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Authentication methods 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}/auth-methods

**Create Auth Method**

Creates a new authentication method for an issuer.

**Method types:**

- **password** - Traditional username/password. Only one allowed per issuer.
- **email_link** - Passwordless magic links. Only one allowed per issuer.
- **email_otp** - Email one-time passwords. Only one allowed per issuer.
- **passkey** - WebAuthn/FIDO2 authentication. Multiple allowed.
- **totp** - Time-based OTP (authenticator apps). Only one allowed per issuer.
- **backup_codes** - Recovery codes. Only one allowed per issuer.
- **oidc** - OpenID Connect (Google, Microsoft, Auth0). Multiple providers allowed.
- **oauth2** - Generic OAuth 2.0. Multiple providers allowed.
- **apple** - Sign in with Apple. Multiple allowed.
- **github** - GitHub OAuth. Multiple allowed.

**Required settings by method:**

- **oidc**: `issuer_url`, `client_id`, `client_secret`
- **oauth2**: `provider`, `client_id`, `client_secret`, `redirect_uri`
- **apple**: `client_id`, `team_id`, `key_id`, `private_key`
- **github**: `client_id`, `client_secret`

Other methods have optional settings.

### 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`

One of (variant 1):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `enabled_login` | boolean | Optional |  |
| `enabled_signup` | boolean | Optional |  |
| `featured` | boolean | Optional |  |
| `first_factor_only` | true | Required |  |
| `method` | oauth2 | Required |  |
| `settings` | object | Required |  |

One of (variant 2):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `enabled_login` | boolean | Optional |  |
| `enabled_signup` | boolean | Optional |  |
| `featured` | boolean | Optional |  |
| `first_factor_only` | true | Required |  |
| `method` | oidc | Required |  |
| `settings` | object | Required |  |

One of (variant 3):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `enabled_login` | boolean | Optional |  |
| `enabled_signup` | boolean | Optional |  |
| `featured` | boolean | Optional |  |
| `first_factor_only` | true | Required |  |
| `method` | apple | Required |  |
| `settings` | object | Required |  |

One of (variant 4):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `enabled_login` | boolean | Optional |  |
| `enabled_signup` | boolean | Optional |  |
| `featured` | boolean | Optional |  |
| `first_factor_only` | true | Required |  |
| `method` | github | Required |  |
| `settings` | object | Required |  |

One of (variant 5):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `enabled_login` | boolean | Optional |  |
| `enabled_signup` | boolean | Optional |  |
| `featured` | boolean | Optional |  |
| `first_factor_only` | true | Required |  |
| `method` | oauth2_manual | Required |  |
| `settings` | object | Required |  |

One of (variant 6):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `enabled_login` | boolean | Optional |  |
| `enabled_signup` | boolean | Optional |  |
| `featured` | boolean | Optional |  |
| `first_factor_only` | true | Required |  |
| `method` | password | Required |  |
| `settings` | object | Required |  |

One of (variant 7):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `enabled_login` | boolean | Optional |  |
| `enabled_signup` | boolean | Optional |  |
| `featured` | boolean | Optional |  |
| `first_factor_only` | true | Required |  |
| `method` | temporary_password | Required |  |
| `settings` | object | Optional |  |

One of (variant 8):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `enabled_login` | boolean | Optional |  |
| `enabled_signup` | boolean | Optional |  |
| `featured` | boolean | Optional |  |
| `first_factor_only` | true | Required |  |
| `method` | email_link | Required |  |
| `settings` | object | Required |  |

One of (variant 9):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `enabled_login` | boolean | Optional |  |
| `enabled_signup` | boolean | Optional |  |
| `featured` | boolean | Optional |  |
| `first_factor_only` | true | Required |  |
| `method` | email_otp | Required |  |
| `settings` | object | Optional |  |

One of (variant 10):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `enabled_login` | boolean | Optional |  |
| `enabled_signup` | boolean | Optional |  |
| `featured` | boolean | Optional |  |
| `first_factor_only` | true | Required |  |
| `method` | sms_otp | Required |  |
| `settings` | object | Optional |  |

One of (variant 11):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `enabled_login` | boolean | Optional |  |
| `enabled_signup` | boolean | Optional |  |
| `featured` | boolean | Optional |  |
| `first_factor_only` | boolean | Required |  |
| `method` | passkey | Required |  |
| `settings` | object | Required |  |

One of (variant 12):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `enabled_login` | boolean | Optional |  |
| `enabled_signup` | boolean | Optional |  |
| `featured` | boolean | Optional |  |
| `first_factor_only` | false | Required |  |
| `method` | totp | Required |  |
| `settings` | object | Optional |  |

One of (variant 13):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `enabled_login` | boolean | Optional |  |
| `enabled_signup` | boolean | Optional |  |
| `featured` | boolean | Optional |  |
| `first_factor_only` | false | Required |  |
| `method` | backup_codes | Required |  |
| `settings` | object | Optional |  |


### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Authentication method 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` |
| 409 | **Conflict** - The request conflicts with the current state of the resource. | `ApiError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/auth-methods/{method_id}

**Get Auth Method**

Retrieves a specific authentication method by ID.

Returns the full configuration for the authentication method including:
- **Method type** - The authentication mechanism (password, passkey, oidc, etc.)
- **Display name** - Human-readable name shown to users
- **Status flags** - Whether enabled for login/signup
- **Settings** - Method-specific configuration

**Note:** Sensitive settings like OAuth client secrets are not returned in the response.

### 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 |
| `method_id` | string | Required | The unique identifier of the authentication method |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Authentication method 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}/auth-methods/{method_id}

**Update Auth Method**

Updates an existing authentication method.

**Updatable fields:**

- **name** - Display name shown to users
- **enabled_login** - Whether users can sign in with this method
- **enabled_signup** - Whether new users can register with this method
- **featured** - Whether to highlight this method in the login UI

**Note:** The method type and core settings (like OAuth client credentials) cannot be changed after creation. To change these, delete the method and create a new one.

**Common operations:**

- **Disable a method temporarily**: Set `enabled_login: false`
- **Feature a new method**: Set `featured: true` to highlight it
- **Stop new signups**: Set `enabled_signup: false` while keeping login enabled

### 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 |
| `method_id` | string | Required | The unique identifier of the authentication method |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Optional | A name for the resource. |
| `enabled_login` | boolean | Optional |  |
| `enabled_signup` | boolean | Optional |  |
| `featured` | boolean | Optional |  |
| `settings` | object | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Authentication method 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}/auth-methods/{method_id}

**Delete Auth Method**

Deletes an authentication method from an issuer.

**Warning:** This action is permanent and cannot be undone.

**Before deleting, consider:**

- Users who only have this authentication method will lose access
- Any OAuth integrations will stop working immediately
- If this is the only login method, no users will be able to sign in

**Alternative:** Instead of deleting, you can disable the method by setting `enabled_login: false` to prevent new logins while preserving the configuration.

### 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 |
| `method_id` | string | Required | The unique identifier of the authentication method |

### 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` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |