Skip to content

API Keys

API keys give CI/CD pipelines, scripts and other systems access to your organization without a user session. A key carries a role that caps what it can do: its effective role is the lower of the key's role and its creator's current role, and a key stops working if its creator is deactivated. Within that cap it can do what a user with that role can do (see Identity & Access).

Managing API keys

Navigate to Organization > API Keys. Creating a key requires the Admin role (Admin access required); revoking one is allowed for the key's creator or any Admin. Admins see every key in the organization; other roles see only the keys they created.

The list shows each key's Name, Role, Token Prefix (the token's first 8 characters, such as zenfra_a, enough to recognise a key without exposing it), Expires (Never or Expired where relevant), Last Used and Usage count. You can search keys and filter by role.

Creating an API key

Click Create API Token and fill in:

  • Name, for example CI/CD Pipeline
  • Description (optional): what the token is used for
  • Role: Read, Write or Admin (default Write)
  • Expiration: 30 days, 60 days, 90 days (default), 180 days, 365 days or Never

The full token is shown once (Save your API token). Copy it and store it securely; it cannot be retrieved later.

Revoking an API key

Use the delete action on the key's row. Revoke API Token warns that Any automation using this token will stop working. Revocation takes effect immediately.

Using the API

  • Base URL: https://api.zenfra.cloud/api/v1
  • Authentication: Authorization: Bearer <token> on every request.
  • The token's role applies: a request beyond that role is refused with 403 and error code insufficient_role.
  • Errors are JSON with a machine-readable code and a message: {"error": "<code>", "message": "…"}, or on some VCS endpoints code instead of error. Branch on the code, not the message.
  • List endpoints that expose limit and offset default to 100 and cap at 1000; the audit log uses page and page_size; the API key list exposes neither.

Example:

curl -H "Authorization: Bearer zenfra_..." \
  "https://api.zenfra.cloud/api/v1/stacks?limit=50"

Security best practices

  • Give each key the minimum role its job needs; automation that only triggers and approves runs needs Write, not Admin.
  • Prefer an expiration over Never and rotate keys periodically.
  • Use descriptive names so you can tell what each key is used for, and revoke keys that are no longer in use.