Core API Reference

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 — see the Core API overview for authentication, pagination, and idempotency, or try these endpoints in the interactive 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_approval status
Admin reviews and approves/rejects via this API
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`