Service tokens

A service token is a credential issued to an application so it can authenticate to the Alpacon API. Tokens are scoped, can be restricted by IP, rate, and time, and every change is recorded in the audit log.

Create and manage tokens from an application’s Credentials tab.

Issue a token

Set the following when creating a token:

  • Name — a short, identifiable name.
  • Description (optional) — what the token does.
  • Scopes — the permissions granted to the token (select at least one).
  • Expires at — a preset (1 week, 1 month, 3 months, 6 months, 1 year) or a custom date, or no expiration.
  • Reason — required when the selected scopes are medium or high risk (see Risk and approval).

Under advanced settings you can further restrict the token:

  • IP whitelist — limit the token to specific IP addresses or CIDR ranges.
  • Rate limit — cap requests per time unit (for example, 1000/hour).
  • Time restriction — allow access only during specific hours (UTC) and on selected days.

One-time key

After creation, the token key is shown only once. Copy and store it securely—once you close the dialog it can’t be shown again. If you lose it, rotate the token to issue a new key.

Risk and approval

Each token is automatically assigned a risk level—Low, Medium, or High—based on its scopes. Selecting medium- or high-risk scopes requires a reason, and issuing such a token may require administrator approval before it takes effect. While a request is pending, it appears in Approvals.

Token detail

A service token’s detail page has these tabs:

  • Overview — token metadata (application, scopes, risk, status, expiry, usage) and a Change history timeline of every create, update, rotate, disable, and emergency-access event.
  • ACL — the detailed scope and permission breakdown.
  • Security — IP whitelist, rate limit, time restriction, and emergency access (see below). Changes here require a reason and are audited.
  • Activity — the audit log of changes (administrator-only).

Break-glass (emergency access)

In the Security tab’s danger zone, emergency access temporarily lifts a token’s IP and time restrictions during an incident. Rate limits and access-control rules still apply. Emergency access is available to superusers.

  • Activate — specify a duration (1–8 hours) and a reason. Restrictions are lifted only for that window.
  • Deactivate — immediately restores the token’s normal restrictions.

Both activation and deactivation are recorded in the audit log.

Last updated: