API Keys

API keys provide programmatic access to the Runsite Platform Public API. Use them to authenticate requests from CI/CD pipelines, CLI tools, or custom integrations.

Key Format

All API keys use the prefix ak_live_ followed by a random hex string:

ak_live_a1b2c3d4e5f6...

Scopes

Each key is assigned a scope that controls its access level:

Scope	Description
`read`	Read-only access to projects, services, and deployments
`write`	Read + create/update projects, services, env vars, and deployments
`admin`	Full access including delete operations

Managing API Keys

API key management requires JWT authentication (dashboard login).

Create a Key

curl -X POST https://api.runsite.app/api/api-keys \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-deploy", "scope": "write"}'

Response:

{
  "id": "uuid",
  "name": "ci-deploy",
  "key_prefix": "a1b2c3d4",
  "scope": "write",
  "is_active": true,
  "plaintext_key": "ak_live_a1b2c3d4...",
  "last_used_at": null,
  "expires_at": null,
  "created_at": "2026-03-12T10:00:00Z",
  "updated_at": "2026-03-12T10:00:00Z"
}

List Keys

curl https://api.runsite.app/api/api-keys \
  -H "Authorization: Bearer <access_token>"

Rotate a Key

Generates a new secret for an existing key. The old secret is immediately invalidated.

curl -X POST https://api.runsite.app/api/api-keys/{key_id}/rotate \
  -H "Authorization: Bearer <access_token>"

Revoke a Key

curl -X DELETE https://api.runsite.app/api/api-keys/{key_id} \
  -H "Authorization: Bearer <access_token>"

Optional Expiration

You can set an expiration date when creating a key:

{
  "name": "temp-access",
  "scope": "read",
  "expires_at": "2026-06-01T00:00:00Z"
}

Expired keys are automatically rejected during authentication.