Approvals — 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.
Base URL: https://api.authpi.com — explore every endpoint in the
interactive Core API reference.
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:
- User signs up when issuer has approval enabled
- User enters
pending_approvalstatus - Admin reviews and approves/rejects via this API
- User transitions to
active(approved) orblocked(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.approvedon approvaluser.approval.rejectedon 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 |