Skip to content

api-keys.md

Latest commit

 

History

History
108 lines (79 loc) · 3.08 KB

api-keys.md

File metadata and controls

108 lines (79 loc) · 3.08 KB

API Keys

API keys authenticate your application's requests to ZeroAuth. Each key is scoped to your tenant account and tracks usage independently.

Key Format

za_{environment}_{48 hex characters}
  • za_live_... — Production keys (real verification, metered)
  • za_test_... — Sandbox keys (test mode, not metered)

Creating Keys

At Signup

A default live key is automatically created when you sign up:

curl -X POST https://api.zeroauth.dev/api/console/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@co.com", "password": "secure123"}'

Additional Keys

Create additional keys via the console API:

curl -X POST https://api.zeroauth.dev/api/console/keys \
  -H "Authorization: Bearer YOUR_CONSOLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "environment": "live",
    "scopes": ["zkp:verify", "zkp:register", "nonce:create"]
  }'

Response:

{
  "key": "za_live_a1b2c3d4...",
  "id": "uuid",
  "name": "Production Backend",
  "prefix": "za_live_a1b2c3",
  "environment": "live",
  "scopes": ["zkp:verify", "zkp:register", "nonce:create"],
  "warning": "Copy this API key now — it will never be shown again."
}

:::danger Important The raw API key is shown exactly once at creation time. ZeroAuth stores only a SHA-256 hash of the key — it cannot be recovered. If you lose it, revoke and create a new one. :::

Scopes

Each key can be restricted to specific operations:

Scope Description
zkp:verify Verify ZK proofs
zkp:register Register new identities
nonce:create Generate proof nonces
identity:read Read user session/identity info
saml:login Initiate SAML SSO flows
saml:callback Process SAML assertions
oidc:authorize Initiate OIDC flows
oidc:callback Process OIDC callbacks

Default scopes for new keys: zkp:verify, zkp:register, identity:read, nonce:create

Listing Keys

curl https://api.zeroauth.dev/api/console/keys \
  -H "Authorization: Bearer YOUR_CONSOLE_TOKEN"

Returns all keys (active and revoked) with prefix, scopes, environment, and last used timestamp. The raw key is never returned.

Revoking Keys

Revocation is immediate and irreversible:

curl -X DELETE https://api.zeroauth.dev/api/console/keys/KEY_UUID \
  -H "Authorization: Bearer YOUR_CONSOLE_TOKEN"

After revocation, any request using that key returns 401 invalid_api_key.

Security Best Practices

  1. Never commit keys to source control — Use environment variables
  2. Use separate keys per environment — za_live_* for production, za_test_* for development
  3. Restrict scopes — Only grant the permissions each service needs
  4. Rotate regularly — Create a new key, update your services, then revoke the old one
  5. Monitor usage — Check GET /api/console/usage for anomalies

Limits

  • Maximum 10 active keys per tenant account
  • Keys can optionally have an expiration date (set at creation)
  • Rate limits and quotas are applied per-tenant, not per-key