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). Every scope and what it permits is listed in the scopes reference.
  • 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 allowed servers, commands, and file operations for this token. See Command patterns and sudo for how a command entry is matched.
  • 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).

Privileged commands

A service token can run commands that need sudo, with two conditions.

The token’s allowed-command entry has to include the sudo prefix, because entries are matched against the command line you submit, not the command that runs as root. Elevation itself is then decided from the command’s assessed risk: allowed at Low, Medium, and High, refused at Critical. A service token is never queued for a human reviewer, and sudo policies do not apply to it. Every automatic elevation is recorded in Sudo, attributed to the application.

Read Command patterns and sudo before writing those entries—a sudo * entry grants the token unrestricted root access.

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: