Auth API

listApiTokens

GET /api/v2/auth/tokens

Requires: admin role

Every API token of the caller's namespace, newest first, without secrets: only the 8-character prefix, principal, roles, label, expiry, revocation and last use (refreshed at most once a minute) are shown. Tokens from atfgraph.yaml are not listed; they are configuration, not store rows.

Generated Python client internals: atfgraph._generated.api.auth_api.AuthApi.list_api_tokens()

Responses

Example response 200

{
  "items": [
    {
      "active": false,
      "created_at": 0,
      "created_by": "string",
      "expires_at": 0,
      "id": "string",
      "label": "string",
      "last_used_at": 0,
      "prefix": "string",
      "principal": "string",
      "revoked_at": 0,
      "roles": [
        "string"
      ],
      "rotated_from": "string"
    }
  ]
}

createApiToken

POST /api/v2/auth/tokens

Requires: admin role

Issue a bearer credential for a principal of the caller's namespace with the given roles (admin, invoke, worker) and optional label and expiry. The plaintext token is in this response only; the server stores its SHA-256 and never logs it. Configured tokens (atfgraph.yaml auth.tokens) stay authoritative and are checked first; a stored token is consulted only when no configured token matches. Namespaces hold at most 1024 tokens (422 api_tokens_full).

Generated Python client internals: atfgraph._generated.api.auth_api.AuthApi.create_api_token()

Request body

ApiTokenCreate (required)

{
  "principal": "string",
  "roles": [
    "string"
  ]
}

Responses

Example response 201

{
  "active": false,
  "created_at": 0,
  "created_by": "string",
  "expires_at": 0,
  "id": "string",
  "label": "string",
  "last_used_at": 0,
  "prefix": "string",
  "previous_revoked_at": 0,
  "principal": "string",
  "revoked_at": 0,
  "roles": [
    "string"
  ],
  "rotated_from": "string",
  "token": "string"
}

revokeApiToken

DELETE /api/v2/auth/tokens/{id}

Requires: admin role

Revoke a token immediately, bringing forward any rotation grace period. Idempotent: revoking a revoked token returns it unchanged. Requests with the token fail with 401 token_revoked from the next request on; the row is kept for audit and appears in the listing with active false.

Generated Python client internals: atfgraph._generated.api.auth_api.AuthApi.revoke_api_token()

Parameters

Responses

Example response 200

{
  "active": false,
  "created_at": 0,
  "created_by": "string",
  "expires_at": 0,
  "id": "string",
  "label": "string",
  "last_used_at": 0,
  "prefix": "string",
  "principal": "string",
  "revoked_at": 0,
  "roles": [
    "string"
  ],
  "rotated_from": "string"
}

rotateApiToken

POST /api/v2/auth/tokens/{id}/rotate

Requires: admin role

Issue a fresh secret for the same principal, roles, label and expiry and schedule the old token's revocation grace_seconds from now (default 0: immediately, at most 30 days). The new plaintext is in this response only and rotated_from names the replaced token. Only an active token can be rotated (409 token_inactive); requests with the old token fail with 401 token_revoked once the grace period has passed.

Generated Python client internals: atfgraph._generated.api.auth_api.AuthApi.rotate_api_token()

Parameters

Request body

ApiTokenRotate (required)

{
  "grace_seconds": 0
}

Responses

Example response 200

{
  "active": false,
  "created_at": 0,
  "created_by": "string",
  "expires_at": 0,
  "id": "string",
  "label": "string",
  "last_used_at": 0,
  "prefix": "string",
  "previous_revoked_at": 0,
  "principal": "string",
  "revoked_at": 0,
  "roles": [
    "string"
  ],
  "rotated_from": "string",
  "token": "string"
}