Personal API Tokens

Personal access tokens (PATs) allow you to authenticate with the Forgexa API without using your password. Tokens are scoped, rotatable, and can be revoked individually.

List Tokens

Returns all active and revoked tokens for the current user.

GET /api/v1/users/me/api-tokens
Authorization: Bearer <token>

Response 200 OK

[
  {
    "id": "uuid",
    "name": "CI Pipeline",
    "token_prefix": "pat_abc1",
    "scopes": ["read", "write"],
    "is_active": true,
    "last_used_at": "2026-05-15T14:30:00Z",
    "expires_at": "2026-08-14T00:00:00Z",
    "revoked_at": null,
    "created_at": "2026-05-16T00:00:00Z"
  }
]

Create Token

Create a new personal access token. The full token value is returned only once in the response — store it securely.

POST /api/v1/users/me/api-tokens
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "CI Pipeline",
  "scopes": ["read", "write"],
  "expires_in_days": 90
}

Response 201 Created

{
  "id": "uuid",
  "name": "CI Pipeline",
  "token": "pat_a1b2c3d4e5f6...",
  "token_prefix": "pat_a1b2",
  "scopes": ["read", "write"],
  "expires_at": "2026-08-14T00:00:00Z",
  "created_at": "2026-05-16T00:00:00Z"
}

Field	Type	Required	Description
name	string	Yes	Human-readable token name
scopes	string[]	No	Permission scopes (default: all)
expires_in_days	int	No	Expiration in days, 1–365 (default: 90)

WARNING

The token field is only returned at creation time. Copy and store it immediately — it cannot be retrieved again. A maximum of 10 active tokens per user is enforced.

Revoke Token

Permanently revoke a token. Revoked tokens cannot be reactivated.

DELETE /api/v1/users/me/api-tokens/{token_id}
Authorization: Bearer <token>

Response 204 No Content

Using API Tokens

Use the token in the Authorization header, same as JWT tokens:

curl -H "Authorization: Bearer pat_a1b2c3d4e5f6..." \
  https://app.forgexa.net/api/v1/workspaces

API tokens work with all endpoints that accept JWT bearer tokens.