Skip to main content

Authentication

All API requests authenticate with an API key, and every API key belongs to an agent seat (a machine identity — see below).

Agent seats​

An agent seat is a machine identity on your team — a non-human account for an agent or integration. Agent seats hold their own credentials (API keys, OAuth connections, and firehose webhooks) and cannot log in to the Alium platform.

Because credentials live on the seat instead of on a person, your integration keeps running as team members come and go — nothing breaks when the admin who set it up leaves.

API keys must belong to an agent seat. Keys owned by a human user are rejected (401 Unauthorized). A customer admin manages seats under Account → Agent Seats; the number of seats available depends on your plan.

API key​

Pass your agent seat's API key in the Authorization header:

Authorization: Token YOUR_API_KEY

API keys are prefixed with alm_ (for example, alm_1a2b3c4d…).

warning

The API key must be sent in the Authorization header. Passing it as a query parameter is not supported.

Managing API keys​

API keys are created and rotated per agent seat, under Account → Agent Seats (customer admins only):

  1. Open the agent seat that should own the key (or create a seat first).
  2. Issue or rotate its API key.
  3. Copy the key immediately — the full value is shown only once. Alium stores only a hash and can never display it again.

Each agent seat has one active API key. Rotating issues a new key and revokes the old one — use it if a key is lost or compromised.

note

The Account → API page is now API reference documentation only. Key management lives under Agent Seats.

Prerequisites​

API access requires:

  • The vendor_api feature enabled on your account. If you receive a 403 Forbidden, contact your Alium customer success representative to enable API access.
  • At least one agent seat with an API key (see above).

Example request​

curl -H "Authorization: Token YOUR_API_KEY" \
  "https://app.alium.io/api/v1/transcripts"

Unauthorized response​

If the API key is missing, invalid, revoked, or owned by a human user rather than an agent seat, you'll receive:

HTTP/1.1 401 Unauthorized
{
  "error": "Unauthorized"
}