How Invariance authenticates requests across five distinct authorization tiers.
Invariance uses Bearer token authentication. All API requests (except health check and docs) require an Authorization: Bearer <token> header.
curl -H "Authorization: Bearer <your-token>" \
https://api.invariance.dev/v1/sessionsTokens are resolved in priority order: admin key first, then developer keys, organization keys, API keys, and finally agent keys. The first match determines the request's scope and permissions.
Invariance supports five authentication tiers, each scoped to a different level of access.
The admin key grants unrestricted access to every API endpoint. Never expose it in client-side code or commit it to version control.
# Set in your environment
export ADMIN_KEY="your-secret-admin-key"dev_POST /v1/identity/signup// Sign up to get a developer key
const res = await fetch('https://api.invariance.dev/v1/identity/signup', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: 'dev@example.com',
name: 'Alice',
}),
});
const { api_key } = await res.json();
// api_key: "dev_abc123..." — scoped to your resourcesorg_POST /v1/identity/orgs// Create an org (requires a developer key)
const res = await fetch('https://api.invariance.dev/v1/identity/orgs', {
method: 'POST',
headers: {
'Authorization': 'Bearer dev_abc123...',
'Content-Type': 'application/json',
},
body: JSON.stringify({ name: 'acme' }),
});
const { api_key } = await res.json();
// api_key: "org_xyz789..." — scoped to org resourcesinv_POST /v1/api-keysapi_keys tableAPI keys provide fine-grained, custom-scoped access. They are stored in the api_keys table and can be revoked independently without affecting other credentials.
Each agent receives its own API key when registered. This key is scoped exclusively to the agent's sessions and receipts, enforcing the principle of least privilege.
Ed25519 keypairs are used for signing receipts and A2A messages. Generate them with the SDK:
import { Invariance } from '@invariance/sdk';
const { privateKey, publicKey } = Invariance.generateKeypair();
// privateKey: 64-char hex string (32 bytes)
// publicKey: 64-char hex string (32 bytes)The private key stays on the agent. The public key is registered with the Invariance server so that receipts and A2A messages can be verified.
For multi-agent systems, you can derive unique keypairs from a single master key using HKDF (HMAC-based Key Derivation Function). This lets you manage one secret while giving each agent a distinct identity.
import { deriveAgentKeypair } from '@invariance/sdk';
const derived = deriveAgentKeypair(masterPrivateKey, 'acme/compliance-agent');
// Deterministic: same inputs always produce the same keypair
// Server only sees the public keyDerivation is deterministic — the same master key and agent identifier always produce the same keypair. This makes key management straightforward: back up the master key, and all agent keys can be regenerated.