Core API Reference

Personal Tokens — Core API

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

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}/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`