Authentication¶

Every request to the Companions API must be authenticated. Programmatic access uses an API key sent in the Authorization header:

Authorization: ApiKey cmp_live_...

The scheme keyword is ApiKey (not Bearer). Requests without a valid key are rejected with 401.

Keep your key secret

An API key carries your account's full programmatic access and spends your balance. Treat it like a password: store it in an environment variable or a secrets manager, never commit it to source control, and never expose it in client-side code.

Getting a key¶

API keys are minted from your account dashboard, or programmatically via POST /v1/account/keys. The plaintext key is shown exactly once at creation and is never retrievable again — copy it immediately. You can hold up to 5 active keys; revoke one to free a slot.

Using a key¶

Send the key on every request. The examples below read it from a COMPANIONS_API_KEY environment variable.

cURLPythonJavaScriptTypeScript

curl https://api.humx.ai/v1/billing/balance \
  -H "Authorization: ApiKey $COMPANIONS_API_KEY"

import os, requests

session = requests.Session()
session.headers["Authorization"] = f"ApiKey {os.environ['COMPANIONS_API_KEY']}"

r = session.get("https://api.humx.ai/v1/billing/balance")
r.raise_for_status()
print(r.json())

const res = await fetch("https://api.humx.ai/v1/billing/balance", {
  headers: { Authorization: `ApiKey ${process.env.COMPANIONS_API_KEY}` },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());

const apiKey = process.env.COMPANIONS_API_KEY!;

const res = await fetch("https://api.humx.ai/v1/billing/balance", {
  headers: { Authorization: `ApiKey ${apiKey}` },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const balance: { balance: number } = await res.json();
console.log(balance);

Rotating and revoking¶

Keys are independent — mint a fresh key, cut traffic over to it, then revoke the old one with DELETE /v1/account/keys/{key_id}. Revocation is immediate.