Access Tokens

Access tokens are organization-scoped bearer tokens for CLI-style and headless surfaces. Each token has a memorable name, optional scopes, an optional expiration, and an audit trail of last use. Tokens are stored as SHA-256 hashes. The plain token is returned only on creation and rotation.

Base URL

/api/v1/admin/access-tokens

Endpoints

Method	Path	Description
`POST`	`/api/v1/admin/access-tokens`	Create an access token
`GET`	`/api/v1/admin/access-tokens`	List access tokens
`GET`	`/api/v1/admin/access-tokens/:id`	Get an access token
`POST`	`/api/v1/admin/access-tokens/:id/revoke`	Revoke an access token
`POST`	`/api/v1/admin/access-tokens/:id/rotate`	Rotate an access token

Scopes

Scopes restrict what the token can do. Common values include:

admin or owner — full organization admin access
cli:read
cli:write

Create an access token

curl -X POST https://api.allternit.com/api/v1/admin/access-tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Local CLI",
    "scopes": "cli:read,cli:write",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Request body

{
  "name": "Local CLI",
  "scopes": "cli:read,cli:write",
  "expires_at": "2026-12-31T23:59:59Z"
}

Response

{
  "id": "at_01hqx8x7x7x7x7x7x7x7x7x",
  "org_id": "org_01hqx8x7x7x7x7x7x7x7x7x",
  "name": "Local CLI",
  "token": "at-abc12345-xyz67890-qwerty1234567890",
  "token_prefix": "at-abc12",
  "scopes": ["cli:read", "cli:write"],
  "expires_at": "2026-12-31T23:59:59Z",
  "created_at": "2026-08-13T18:00:00Z"
}

Save the token immediately. It cannot be retrieved later.

List access tokens

curl -X GET https://api.allternit.com/api/v1/admin/access-tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response

{
  "items": [
    {
      "id": "at_01hqx8x7x7x7x7x7x7x7x7x",
      "org_id": "org_01hqx8x7x7x7x7x7x7x7x7x",
      "name": "Local CLI",
      "token_prefix": "at-abc12",
      "scopes": ["cli:read", "cli:write"],
      "expires_at": "2026-12-31T23:59:59Z",
      "created_at": "2026-08-13T18:00:00Z",
      "last_used_at": "2026-08-13T18:30:00Z",
      "revoked_at": null
    }
  ]
}

Get an access token

curl -X GET https://api.allternit.com/api/v1/admin/access-tokens/at_01hqx8x7x7x7x7x7x7x7x7x \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response

{
  "id": "at_01hqx8x7x7x7x7x7x7x7x7x",
  "org_id": "org_01hqx8x7x7x7x7x7x7x7x7x",
  "name": "Local CLI",
  "token_prefix": "at-abc12",
  "scopes": ["cli:read", "cli:write"],
  "expires_at": "2026-12-31T23:59:59Z",
  "created_at": "2026-08-13T18:00:00Z",
  "last_used_at": "2026-08-13T18:30:00Z",
  "revoked_at": null
}

Revoke an access token

curl -X POST https://api.allternit.com/api/v1/admin/access-tokens/at_01hqx8x7x7x7x7x7x7x7x7x/revoke \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response

{
  "status": "revoked",
  "revoked_at": "2026-08-13T18:35:00Z"
}

Revoked tokens can no longer authenticate.

Rotate an access token

curl -X POST https://api.allternit.com/api/v1/admin/access-tokens/at_01hqx8x7x7x7x7x7x7x7x7x/rotate \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response

{
  "token": "at-new12345-xyz67890-qwerty1234567890",
  "token_prefix": "at-new12",
  "record": {
    "id": "at_01hqx8x7x7x7x7x7x7x7x7x",
    "org_id": "org_01hqx8x7x7x7x7x7x7x7x7x",
    "name": "Local CLI",
    "token_prefix": "at-new12",
    "scopes": ["cli:read", "cli:write"],
    "expires_at": "2026-12-31T23:59:59Z",
    "created_at": "2026-08-13T18:35:00Z",
    "last_used_at": null,
    "revoked_at": null
  }
}

Rotation issues a new token, updates the prefix, and clears any previous revocation.

Authenticate with an access token

curl -X GET https://api.allternit.com/api/v1/admin/workspaces \
  -H "Authorization: Bearer at-abc12345-xyz67890-qwerty1234567890"

The token is authenticated by hashing the bearer value and matching it against stored hashes. On success, last_used_at is updated.

Error codes

Status	Code	Description
`400`	`invalid_name`	Name must be 1–128 characters.
`401`	`invalid_token`	Token is revoked, expired, or does not exist.
`403`	`organization_required`	Caller is not associated with an organization.
`403`	`insufficient_role`	Caller is not an organization owner or admin.
`404`	`token_not_found`	Access token does not exist.

Service accounts — machine identities with client credentials
Workspaces — scope tokens to workspaces

Get Started

Core Concepts

Gizzi Code CLI

Tools & ACI

Security & Enterprise

Admin API

BYOC Runtime

Surfaces

CI CD

Guides

Cookbooks

Release Notes

Access Tokens

Access Tokens

Base URL

Endpoints

Scopes

Create an access token

Request body

Response

List access tokens

Response

Get an access token

Response

Revoke an access token

Response

Rotate an access token

Response

Authenticate with an access token

Error codes

​Access Tokens

​Base URL

​Endpoints

​Scopes

​Create an access token

​Request body

​Response

​List access tokens

​Response

​Get an access token

​Response

​Revoke an access token

​Response

​Rotate an access token

​Response

​Authenticate with an access token

​Error codes

​Related pages

Access Tokens

Base URL

Endpoints

Scopes

Create an access token

Request body

Response

List access tokens

Response

Get an access token

Response

Revoke an access token

Response

Rotate an access token

Response

Authenticate with an access token

Error codes

Related pages