Personal Access Tokens¶

Overview¶

Personal Access Tokens (PATs) are long-lived opaque tokens that authenticate to the JustIAM REST API with the same privileges as the owning user. They are primarily intended for:

Service accounts that need programmatic API access
CI/CD pipelines and automation scripts
API access when interactive OAuth2 isn't practical (e.g., the Terraform provider)

Self-service PATs (regular users)¶

Any authenticated user can create PATs for themselves.

Create a token¶

UI: Profile → Personal Access Tokens → New Token

API:

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

{
  "name": "CI pipeline",
  "expires_in_days": 90
}

Response:

{
  "id": "<uuid>",
  "name": "CI pipeline",
  "token": "justiam_pat_xxxxxxxxxxxxxxxx",
  "expires_at": "2025-03-01T00:00:00Z"
}

Warning

The token value is only shown once at creation time. Store it securely.

expires_in_days must be between 1 and 365.

List tokens¶

GET /api/v1/me/tokens?page=1&limit=25

Query param	Default	Description
`page`	`1`	Page number
`limit`	`20`	Items per page (max 100)

Returns a paginated list of token metadata (name, created_at, expires_at, last_used_at). The token value itself is never returned after creation.

Response shape:

{
  "data": [ /* PATRecord objects */ ],
  "total": 5,
  "page": 1,
  "limit": 25
}

Revoke a token¶

DELETE /api/v1/me/tokens/{id}

Service account PATs¶

Service accounts (is_service_account = true) cannot log in interactively; they authenticate exclusively with PATs. A user with service_accounts.tokens permission can manage their tokens.

Create a service account PAT¶

POST /api/v1/users/{serviceAccountId}/tokens
Authorization: Bearer <admin-jwt>
Content-Type: application/json

{
  "name": "Terraform runner",
  "expires_in_days": 365
}

List / revoke¶

GET    /api/v1/users/{id}/tokens
DELETE /api/v1/users/{id}/tokens/{tokenId}

Using a PAT¶

Pass the token as a Bearer token in the Authorization header:

GET /api/v1/users
Authorization: Bearer justiam_pat_xxxxxxxxxxxxxxxx

Terraform provider¶

The Terraform provider supports authentication via a PAT (or any JWT):

provider "justiam" {
  endpoint = "https://justiam.example.com"
  token    = var.justiam_token
}

Set the token via the JUSTIAM_TOKEN environment variable to avoid storing it in state.