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

# Approvals — AuthPI Core API

Signup approval queue management. When an issuer has signup approval enabled, new user signups enter a pending_approval state and must be reviewed by admins before becoming active.

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

**List Pending Approvals**

Lists all users pending approval for an issuer with pagination.

This endpoint returns users who have completed signup but are awaiting admin review before their accounts become active. Only users with `status === "pending_approval"` are returned.

**Approval workflow:**
1. User signs up when issuer has approval enabled
2. User enters `pending_approval` status
3. Admin reviews and approves/rejects via this API
4. User transitions to `active` (approved) or `blocked` (rejected)

**Results are sorted by signup time (oldest first)** so admins can process in order of arrival.

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

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

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Paginated list of pending approvals | `object` |
| 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}/approvals/{user_id}

**Get Approval Details**

Retrieves full details for a user pending approval.

Returns the complete user profile including:

- **Profile data** - Username, email, name, and custom metadata
- **Approval metadata** - Signup reason, triggered rule, timestamps
- **Status** - Current pending_approval status

Use this endpoint to review a user's signup details before making an approval decision.

**Note:** This endpoint only returns users with `status === "pending_approval"`. For users that have already been approved or rejected, use the standard Get User 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 |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | User pending approval 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` |
| 422 | **Unprocessable Entity** - The request is well-formed but contains semantic errors. | `ApiError` |

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

**Update Approval**

Approve or reject a pending user signup.

**Approve:** Transitions user from `pending_approval` to `active` status.
- User can now authenticate
- Optional admin note for internal records

**Reject:** Transitions user from `pending_approval` to `blocked` status.
- User cannot authenticate
- Rejection reason is stored and may be shown to user
- Optional admin note for internal records

**Events emitted:**
- `user.approval.approved` on approval
- `user.approval.rejected` on rejection

**Authorization:** Requires admin permissions on the issuer.

### 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 |
| --- | --- | --- | --- |
| `action` | approve \| reject | Required | The action to take: approve or reject the user |
| `reason` | string | Optional | Rejection reason shown to user (required when action is 'reject') |
| `note` | string | Optional | Internal admin note (not shown to user) |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | User approval status 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` |
| 422 | **Unprocessable Entity** - The request is well-formed but contains semantic errors. | `ApiError` |