Authentication

Overview

The only public origin is https://api.allternit.com (Cloud API). Credentials depend on what you are calling.

Credential	Header	Used for
Clerk session JWT	`Authorization: Bearer <sess>`	Browser console: pairing, relay, agent-sessions, office, beta, billing, provisioned instances
Virtual key (`ak-`)	`Authorization: Bearer ak-…`	LLM gateway `/v1/chat/completions`, embeddings, files, batches
Runtime device token (`allternit_runtime_…`)	`Authorization: Bearer allternit_runtime_…`	Node → Cloud API: heartbeat, relay connect, rotate

Organization-scoped admin routes under /api/v1/gateway/* require a Clerk JWT and an organization owner or admin role. The Allternit API on :8013 is not a public auth surface. Production clients do not send tokens there. Relayed requests forward the original Clerk Authorization header to the node.

Local development may call http://127.0.0.1:8013 on the same machine. That is the data plane, not a second production API.

LLM gateway virtual keys

The Allternit LLM gateway uses virtual keys for authentication. Each virtual key is a scoped, rotatable credential that maps to a tenant, organization, or user profile. Virtual keys are used for all public /v1 gateway routes, including chat completions, embeddings, files, and batches.

Virtual keys

Virtual keys start with ak-. The gateway stores only the SHA-256 hash of the key; the plaintext is shown once at creation and cannot be recovered.

curl https://api.allternit.com/v1/chat/completions \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'

Base URL

Public Cloud API (LLM gateway):

https://api.allternit.com/v1

Local Allternit API (desktop / cargo run -p allternit-api only):

http://127.0.0.1:8013/v1

Create a virtual key

This endpoint requires a Clerk JWT and organization owner or admin role.

curl -X POST https://api.allternit.com/api/v1/gateway/keys \
  -H "Authorization: Bearer $ALLTERNIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-chat",
    "monthly_budget_cents": 10000,
    "rate_limit_rpm": 600,
    "allowed_models": ["auto", "allternit-balanced", "allternit-code"]
  }'

Request body

Field	Type	Required	Description
`name`	string	no	Human-readable name for the key.
`monthly_budget_cents`	integer	no	Monthly spend cap in cents. `0` or omitted means no cap.
`rate_limit_rpm`	integer	no	Requests-per-minute limit. Must be at least `1` when provided.
`allowed_models`	string[]	no	Model ids and policy aliases this key may use. Omit to allow all.

Example response

{
  "id": "key_abc123",
  "name": "production-chat",
  "key_prefix": "ak-prod",
  "key": "ak-prod-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "warning": "This key is shown only once. Store it securely.",
  "monthly_budget_cents": 10000,
  "rate_limit_rpm": 600,
  "allowed_models": ["auto", "allternit-balanced", "allternit-code"],
  "created_at": 1723500000
}

List virtual keys

curl https://api.allternit.com/api/v1/gateway/keys \
  -H "Authorization: Bearer $ALLTERNIT_TOKEN"

{
  "keys": [
    {
      "id": "key_abc123",
      "name": "production-chat",
      "key_prefix": "ak-prod",
      "monthly_budget_cents": 10000,
      "rate_limit_rpm": 600,
      "allowed_models": ["auto", "allternit-balanced", "allternit-code"],
      "created_at": 1723500000
    }
  ]
}

Update a virtual key

curl -X PATCH https://api.allternit.com/api/v1/gateway/keys/key_abc123 \
  -H "Authorization: Bearer $ALLTERNIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "monthly_budget_cents": 20000,
    "allowed_models": ["auto"]
  }'

Revoke a virtual key

curl -X DELETE https://api.allternit.com/api/v1/gateway/keys/key_abc123 \
  -H "Authorization: Bearer $ALLTERNIT_TOKEN"

{
  "id": "key_abc123",
  "revoked": true
}

Authentication errors

HTTP status	Code	Meaning
401	`allternit.authentication_failed`	Missing, malformed, or invalid virtual key.
401	`invalid_request_error`	Key is revoked or expired.
403	`allternit.permission_denied`	Key is not allowed to use the requested model.
429	`allternit.rate_limited`	Per-key rate limit exceeded.
429	`allternit.budget_exceeded`	Monthly key, tenant, or organization budget exhausted.

Security best practices

Never commit virtual keys to version control.

Store keys in environment variables or a secrets manager.
Rotate keys regularly and revoke unused keys.
Use separate keys for production, staging, and development.
Set monthly_budget_cents and rate_limit_rpm on every key.
Restrict allowed_models to the smallest set required.

API Overview
Cloud API
Chat Completions — primary gateway endpoint
Proxy — gateway middleware and request lifecycle
Rate Limits — quota and budget details

Overview

LLM Gateway

Agents & Runtime

Work Queue & Deployments

Files, Webhooks & Sandbox

Tools & Connectors

Collaboration & Workflows

Infrastructure & Platform

Canvases

Onboarding

A Labs

Playground

Users & Profiles

Overview

LLM gateway virtual keys

Virtual keys

Base URL

Create a virtual key

Request body

Example response

List virtual keys

Update a virtual key

Revoke a virtual key

Authentication errors

Security best practices

​Overview

​LLM gateway virtual keys

​Virtual keys

​Base URL

​Create a virtual key

​Request body

​Example response

​List virtual keys

​Update a virtual key

​Revoke a virtual key

​Authentication errors

​Security best practices

​Related pages

Overview

LLM gateway virtual keys

Virtual keys

Base URL

Create a virtual key

Request body

Example response

List virtual keys

Update a virtual key

Revoke a virtual key

Authentication errors

Security best practices

Related pages