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

# Clients — AuthPI Core API

OAuth 2.0 client management endpoints. Clients are applications that authenticate users via your Issuers. Each client has its own credentials, redirect URIs, and permissions.

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

**List Clients**

Lists all OAuth 2.0/OIDC clients registered with an issuer.

Clients are applications that authenticate users via your issuer. Each client has credentials and configuration for the OAuth 2.0 flows it supports.

**Client types:**
- **SPA** (Single Page Application) - Public client, uses PKCE, no client secret
- **Native** - Mobile/desktop app, public client, uses PKCE
- **Web** - Server-side application, confidential client with secret
- **M2M** (Machine-to-Machine) - Service account, uses client credentials flow

Use the `status` filter to find disabled clients or the `name` filter to search by application name.

### 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 (client ID from previous response) |
| `status` | active \| disabled \| deleted | Optional | Filter by client status (default: excludes deleted) |
| `name` | string | Optional | Filter by name (case-insensitive contains match) |

### Responses

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

**Create Client**

Creates a new OAuth 2.0/OIDC client for an issuer.

A client represents an application that will authenticate users via your issuer. Choose the appropriate client type based on your application:

**Client types:**
- **SPA** - Browser-based applications (React, Vue, Angular). Public client, requires PKCE.
- **Native** - Mobile or desktop applications. Public client, requires PKCE.
- **Web** - Server-side applications (Node.js, Python, Go). Confidential client with secret.
- **M2M** - Machine-to-machine communication. Uses client credentials flow only.

**Security considerations:**
- **Confidential clients** receive a client secret - store it securely and never expose it client-side
- **Public clients** must use PKCE (Proof Key for Code Exchange) - we enforce S256 by default
- Configure the minimum required scopes and grant types
- Register only the redirect URIs your application actually uses

**Important:** The client secret is only returned once at creation. Store it immediately - you cannot retrieve it later.

### 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 | Required | A name for the resource. |
| `type` | internal \| external | Required |  |
| `confidential` | boolean | Required |  |
| `settings` | object | Required |  |
| `description` | string \| null | Optional |  |
| `logo_url` | string | Optional | A URL |
| `secret` | string | Optional |  |
| `metadata` | Metadata | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Client 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}/clients/{client_id}

**Get Client**

Retrieves the full configuration of an OAuth 2.0/OIDC client by its ID.

An OAuth Client represents an application that authenticates users via your issuer. This endpoint returns all client settings including:

- **Credentials** - Client ID (secret is never returned after creation)
- **Redirect URIs** - Allowed callback URLs for OAuth flows
- **Grant types** - Enabled OAuth flows (authorization_code, refresh_token, client_credentials)
- **Scopes** - Permitted OAuth scopes
- **Token settings** - Access token lifetime, refresh token rotation policy
- **PKCE settings** - Code challenge requirements for public clients

Use this endpoint to verify client configuration or before making 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 |
| `client_id` | string | Required | The unique identifier of the OAuth client |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Client configuration 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}/clients/{client_id}

**Update Client**

Updates an OAuth 2.0/OIDC client's configuration.

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

**Commonly updated settings:**
- **Redirect URIs** - Add or remove allowed callback URLs
- **Scopes** - Adjust permitted OAuth scopes
- **Grant types** - Enable or disable OAuth flows
- **Token settings** - Modify access token lifetime or refresh token policy
- **Display settings** - Update name, description, or logo

**Important considerations:**
- Removing a redirect URI that's in use will cause active OAuth flows to fail
- Reducing scopes won't revoke existing tokens, but new tokens will have reduced access
- Disabling a grant type takes effect immediately for new requests
- To rotate the client secret, use the dedicated rotate endpoint instead

### 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 |
| `client_id` | string | Required | The unique identifier of the OAuth client |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Optional | A name for the resource. |
| `status` | active \| disabled | Optional |  |
| `description` | string \| null | Optional |  |
| `logo_url` | string \| null | Optional | A URL |
| `settings` | object | Optional |  |
| `metadata` | Metadata | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Client 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}/clients/{client_id}

**Delete Client**

Deletes an OAuth 2.0/OIDC client (soft delete).

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

- **OAuth flows fail** - Authorization and token requests return an error
- **Existing tokens remain valid** - Until they expire naturally
- **Recovery is possible** - Contact support to restore within the grace period

**Before deleting:**
1. Ensure no production applications depend on this client
2. Consider disabling the client first to test impact
3. Update any integrations to use a different client ID

**After deletion:**
- The client ID becomes unavailable for reuse
- Associated refresh tokens will fail on next rotation
- Data is permanently deleted after the 31-day 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 |
| `client_id` | string | Required | The unique identifier of the OAuth client |

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

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/clients/{client_id}/secret/rotate

**Rotate Client Secret**

Rotates the client secret for a confidential OAuth 2.0 client.

Secret rotation is a security best practice that should be performed periodically or after a suspected compromise.

**Rotation process:**
1. A new secret is generated and returned in the response
2. The old secret remains valid for 15 minutes (grace period)
3. Update your application with the new secret
4. After 15 minutes, only the new secret works

**Best practices:**
- Rotate secrets periodically (e.g., every 90 days)
- Rotate immediately if a secret may have been exposed
- Test the new secret in staging before the grace period expires
- Store the new secret securely - it cannot be retrieved again

**Important:** This endpoint only works for confidential clients. Public clients (SPA, native) don't have secrets and will return a 400 error.

### 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 |
| `client_id` | string | Required | The unique identifier of the OAuth client |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Secret rotated 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` |