API Tokens for Automation

An API token is a long-lived, named, revocable credential for anything that talks to Athena without a person at the keyboard: PowerShell scripts, scheduled tasks, CI pipelines and other REST clients. A token acts as you, never with more than you hold at the moment it is used, and, unlike an interactive sign-in, it keeps working across server restarts until it expires or is revoked.

Why use an API token instead of a password#

A normal sign-in (password, LDAP or SSO) gives you a short-lived session token. That is right for a person, but awkward for automation: the session expires on the Token Expiration clock, and with the default signing-key rotation every server restart signs it out (see Sessions & Server Restarts). An unattended script would have to store a password and sign in again and again.

An API token avoids both problems:

• Survives restarts. The token is stored by the server (as a hash), not signed with the session key, so restarting the server does not invalidate it.
• Explicit lifetime. You pick how many days it lives (default 30), up to the maximum an administrator allows.
• Named and revocable. Each token has a label such as CI deploy, so you can see where it is used and cut off just that one.
• Optionally scoped. You can limit a token to a few permissions, for example read-only access to agents for a reporting script.
• No password in your scripts. Revoking a leaked token does not require changing your password.

How a token is authorised#

• It acts as its owner, as the owner is right now. Each request is checked against the owner’s current role. If you are moved to a role with fewer permissions, all of your tokens lose those permissions on their next request.
• Scope can only narrow. A token limited to selected permissions gets the overlap of that list and its owner’s current permissions. You can only pick permissions you hold when you create the token. Asking for one you don’t hold is refused with “A token cannot hold more than its owner. Not held: …”
• It stops working on the next request when it is revoked, when it expires, or when its owner’s account is disabled or deleted. Deleting a user also removes their tokens.
• Account lockout does not affect tokens. A lockout caused by failed password sign-ins (see Login Rate Limiting) does not disable that user’s tokens. This means someone guessing passwords cannot shut down your automation.
• A token cannot create tokens. New tokens must be created from an interactive session (the console, or a PowerShell session connected with a password or SSO).
• API and PowerShell only. Tokens are accepted by the REST API (/api/…) and therefore by the PowerShell module. They cannot be used to sign in to the web console.
• Per server. A token is valid only on the Athena server that issued it. Settings Sync does not copy tokens to other servers.

Who can use API tokens#

If you don’t have apitokens.use, the API Tokens panel does not appear on your profile. See Permission Model & Role Bundles for how permissions map to roles.

Creating a token in the console#

1. Click your initials badge in the top bar and choose Profile.
2. In the API Tokens panel, click New token.
3. In the New API token dialog, fill in:
   • Name: a label you will recognise later, for example CI deploy. Up to 100 characters. It must be unique among your tokens that have not been revoked (case-insensitive).
   • Expires in (days): from 1 up to the maximum set by your administrator. The default is 30.
   • Limit to selected permissions (optional): tick it and choose permissions from the list of those you currently hold. Leave it unticked to give the token everything you hold.
4. Click New token. The dialog closes and the panel shows the secret, which starts with ath_, along with a copy button and this warning: “Copy this token now. Only its hash is stored, so it cannot be shown again.”

The panel lists all your tokens as name …last4, each with a status (Active, Expired or Revoked), its expiry, when it was last used (or never), and its scope (everything you hold or the list of permissions). If any active token expires within 7 days, the panel shows a “Expiring within 7 days: …” notice naming them. Create the replacement before the old token expires.

Using a token with PowerShell#

PowerShell module 2.14.0 and later can connect with a token in place of a password. Nothing is entered interactively: every request carries the token. On connect, the module checks the token once, so a bad token fails straight away instead of on your first real command:

# Store the secret somewhere safe; this reads it from an environment variable
Connect-Athena -Server athena.example.local -ApiToken $env:ATHENA_API_TOKEN

# Then use any cmdlet as normal
Get-AthenaAgent

-Port still defaults to 8443. A session connected this way has no session-expiry clock of its own: it lasts until the token expires or is revoked. A token session cannot create new tokens.

The module also manages tokens:

# A 90-day token with everything you hold
$t = New-AthenaApiToken -Name "CI deploy" -ExpiresInDays 90
$t.Token   # the ath_ secret - copy it now

# A read-only token for a reporting script
New-AthenaApiToken -Name "inventory report" -Permission agents.view

# Every live token that expires within a week (admins)
Get-AthenaApiToken -All | Where-Object { $_.IsActive -and $_.ExpiresAt -lt (Get-Date).AddDays(7) }

# Revoke a token by name without prompting
Get-AthenaApiToken | Where-Object Name -eq "old laptop" | Revoke-AthenaApiToken -Force

Using a token with the REST API#

Send the token on each request to /api/… in either of these headers:

Authorization: Bearer ath_…
# or
X-Athena-Api-Token: ath_…

curl -H "Authorization: Bearer $ATHENA_API_TOKEN" https://athena.example.local:8443/api/auth/me

If a token is refused, the 401 response has a WWW-Authenticate header with the reason, naming the token by its label and last four characters. For example: Bearer error="invalid_token", error_description="API token 'CI deploy' (...a1f3) is revoked". Other reasons are an expired token (with its expiry time) or an owner who is disabled or removed. A value that is malformed or unknown is reported only as Invalid API token.

Token management endpoints:

POST /api/api-tokens
{
  "name": "CI deploy",
  "expiresInDays": 90,
  "permissions": ["agents.view"]
}

Leave out expiresInDays to get the 30-day default. Leave out permissions to give the token everything you hold. If you send permissions, it must contain at least one permission.

Maximum lifetime policy#

Administrators set the longest lifetime a new token may have in Settings → Security → API Tokens, under API token policy → Maximum lifetime. The allowed range is 1 to 3650 days and the default is 365. Users can choose any lifetime up to this value. Changing it does not affect existing tokens, which keep the expiry they were created with.

A request for a lifetime above the maximum is refused, not shortened. The error is “A token lifetime must be between 1 and N days (Settings > Security > API Tokens).”

Reviewing and revoking everyone’s tokens#

Holders of apitokens.manage also see an All API tokens table on Settings → Security → API Tokens. It has columns for Owner, Token (name and last four characters), Scope, Created, Expires (with an expires within 7 days hint), Last used (time and client IP address), and Status. For revoked tokens, Status shows who revoked them. Each live token has two actions:

• Revoke: revokes that token.
• Revoke all of this user’s tokens: revokes every live token the owner has, for example when someone leaves the team or a laptop is lost.

Revocation takes effect on the token’s next request. The table never shows secrets. The Last used time and address are updated at most once a minute per token.

Audit trail and monitoring#

Token activity is written to the audit log. Every entry names the token by label and last four characters, for example 'CI deploy' (…a1f3):

If you scrape Athena’s Prometheus metrics, the counter athena_api_token_auth_total counts token checks, labelled by result: success, malformed, unknown, revoked, expired, owner_disabled or error. A rise in unknown or revoked usually means a script is still using an old token.

Recommended practices#

• Create one token per script or pipeline and give each a clear name, so you can revoke just that one.
• Limit the scope to what the job needs. A reporting script rarely needs more than view permissions.
• Consider owning automation tokens from a dedicated service account whose role matches the job. Disabling that account stops all of its tokens at once.
• Keep lifetimes short and rotate them. Use the 7-day expiry warnings, or Get-AthenaApiToken -All, to replace tokens before they expire.
• Revoke any token you think has leaked straight away, then check ApiTokenUsed entries for where it was used.