Manage API tokens for programmatic access to the Alpacon API. Each token is scoped to the authenticated user and can be restricted with fine-grained permission scopes.
API tokens cannot be used to manage other API tokens. Only session-based (login) authentication can create, update, or delete tokens.
List
List API tokens
Retrieve a paginated list of API tokens for the authenticated user.
Request
GET /api/auth/tokens/
Query parameters
| Parameter | Type | Description |
|---|
name | string | Filter by exact token name |
enabled | boolean | Filter by enabled status |
remote_ip | string | Filter by exact remote IP address |
search | string | Search across name, user_agent, and remote_ip |
ordering | string | Sort order (added_at, updated_at, -updated_at). Default: -updated_at |
page | integer | Page number |
page_size | integer | Results per page (default: 15, max: 100) |
Response
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "CI/CD pipeline",
"enabled": true,
"scopes": ["server:*", "event:*"],
"updated_at": "2025-01-15T10:30:00Z",
"expires_at": "2025-12-31T23:59:59Z"
},
{
"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"name": "Monitoring",
"enabled": true,
"scopes": ["*"],
"updated_at": "2025-01-10T08:00:00Z",
"expires_at": null
}
]
}
Example
curl -X GET "https://your-workspace.us1.alpacon.io/api/auth/tokens/?enabled=true" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
Create
Create API token
Create a new API token. The token key is only returned in the creation response and cannot be retrieved again.
Request
POST /api/auth/tokens/
Request body
| Field | Type | Required | Description |
|---|
name | string | Yes | Token name (max 128 characters, unique per user) |
enabled | boolean | No | Enable the token immediately (default: true) |
scopes | array | No | Permission scopes (default: ["*"]). Format: "resource:action" |
expires_at | datetime | No | Expiration date (must be a future date, default: never) |
Scope examples:
"*" — full access"server:*" — all server operations"event:*" — all event operations
Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "CI/CD pipeline",
"key": "alpat-xxxxxxxxxxxxxxxxxx",
"enabled": true,
"scopes": ["server:*", "event:*"],
"updated_at": "2025-01-15T10:30:00Z",
"expires_at": "2025-12-31T23:59:59Z"
}
The key field is only included in the creation response. Store it securely — it cannot be retrieved later.
Example
curl -X POST "https://your-workspace.us1.alpacon.io/api/auth/tokens/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
-H "Content-Type: application/json" \
-d '{
"name": "CI/CD pipeline",
"enabled": true,
"scopes": ["server:*", "event:*"],
"expires_at": "2025-12-31T23:59:59Z"
}'
Get
Get API token
Retrieve details of a specific API token.
Request
GET /api/auth/tokens/{token_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
token_id | UUID | Yes | Token ID |
Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "CI/CD pipeline",
"enabled": true,
"scopes": ["server:*", "event:*"],
"updated_at": "2025-01-15T10:30:00Z",
"expires_at": "2025-12-31T23:59:59Z"
}
Example
curl -X GET "https://your-workspace.us1.alpacon.io/api/auth/tokens/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
Update
Update API token
Update properties of an existing API token. Only the fields included in the request body are updated.
Request
PATCH /api/auth/tokens/{token_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
token_id | UUID | Yes | Token ID |
Request body
| Field | Type | Required | Description |
|---|
name | string | No | New token name (max 128 characters, unique per user) |
enabled | boolean | No | Enable or disable the token |
scopes | array | No | Updated permission scopes |
expires_at | datetime | No | New expiration date (must be a future date, or null for no expiry) |
Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "CI/CD pipeline (disabled)",
"enabled": false,
"scopes": ["server:*"],
"updated_at": "2025-01-20T14:00:00Z",
"expires_at": "2025-06-30T23:59:59Z"
}
Example
curl -X PATCH "https://your-workspace.us1.alpacon.io/api/auth/tokens/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'
Delete
Delete API token
Permanently delete an API token. The token is immediately revoked and can no longer be used for authentication.
Request
DELETE /api/auth/tokens/{token_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
token_id | UUID | Yes | Token ID |
Response
204 No Content
Example
curl -X DELETE "https://your-workspace.us1.alpacon.io/api/auth/tokens/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
Deletion is permanent and cannot be undone.