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

# Personal Tokens — AuthPI Core API

User personal access token management. Personal tokens allow users to authenticate scripts and integrations acting on their behalf.

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

**List Personal Tokens**

Lists all personal access tokens for a specific user.

Personal tokens (also called Personal Access Tokens or PATs) allow users to authenticate scripts, CLI tools, and integrations without using their primary credentials.

**Common use cases:**
- CI/CD pipeline authentication
- CLI tool access
- Personal automation scripts
- Third-party app integrations

**Token limits:** Each user can have up to 50 active personal tokens.

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

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional | Maximum number of items to return (1-100, default: 50) |
| `cursor` | string | Optional | Token ID to start after (for pagination) |
| `status` | active \| blocked \| revoked \| expired \| suspended | Optional | Filter by token status (active, blocked, revoked) |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Personal tokens retrieved successfully | `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/{user_id}/tokens

**Create Personal Token**

Creates a new personal access token for a user.

Personal tokens enable users to authenticate scripts, CLI tools, and integrations without exposing their primary credentials. The JWT token is returned **only once** at creation time.

**Important:** Store the `token_plain` value securely. It cannot be retrieved again after this response.

**Token configuration:**
- **name**: A descriptive name for the token (e.g., "CI Pipeline", "CLI Access")
- **scopes**: Permissions granted to this token (e.g., "read:users", "write:api-keys")
- **expires_at**: Optional expiration timestamp (recommended for security)

**Limits:** Each user can have up to 50 active personal tokens.

### 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 |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `description` | string | Optional |  |
| `tags` | string[] | Optional |  |
| `restrictions` | object | Required |  |
| `expires_at` | integer | Optional | Unix timestamp in milliseconds |
| `metadata` | Metadata | Optional |  |
| `type` | personal_token | Required |  |
| `audience` | string | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Personal token created successfully. Store the token_plain JWT securely - it cannot be retrieved again. | `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` |
| 429 | **Too Many Tokens** - User has reached the maximum of 50 personal tokens. Revoke unused tokens before creating new ones. | `ApiError` |

## GET /v1/accounts/{account_id}/tokens/{token_id}

**Get Personal Token**

Retrieves details of a specific personal access token.

Returns metadata about the token including its name, scopes, status, and expiration. The token's secret value is never returned after initial creation.

**Token statuses:**
- **active**: Token can be used for authentication
- **blocked**: Temporarily disabled, can be unblocked
- **revoked**: Permanently disabled, cannot be restored

### Path parameters

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

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Personal token 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` |

## DELETE /v1/accounts/{account_id}/tokens/{token_id}

**Delete Personal Token**

Deletes a personal access token permanently.

This immediately revokes the token and prevents any further authentication attempts. The token data is retained for 31 days before permanent deletion.

**Note:** This action is equivalent to revoking the token with immediate effect and cannot be undone.

### Path parameters

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

### 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}/tokens/{token_id}/revoke

**Revoke Personal Token**

Permanently revokes a personal access token.

This immediately and permanently disables the token. Authentication attempts will fail immediately after revocation.

**What happens:**
- Authentication attempts immediately fail
- The token status changes to "revoked"
- Token data is retained for 31 days for auditing, then permanently deleted

**Use cases:**
- Token compromised or leaked
- Integration permanently decommissioned
- User offboarding

**Note:** Revocation cannot be undone. For temporary suspension, consider blocking the token instead if that feature is available.

### Path parameters

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

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `by` | string | Optional |  |
| `reason` | string | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Personal token revoked 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` |