Authentication

Ivorleaf developer API keys are private, organization-scoped credentials. Use them only from trusted server-side environments.

Bearer authentication

The preferred mechanism is an API key beginning with ivl_ in the Authorization header:

Authorization: Bearer ivl_...

curl "$IVORLEAF_API_BASE_URL/v1/api/usage/status" \
  --header "Authorization: Bearer $IVORLEAF_API_KEY"

X-API-Key: $IVORLEAF_API_KEY is intentionally supported as an alternative. Do not send both. X-Ivorleaf-Client is optional for direct HTTP use and defaults to api; sending a client not permitted by the key returns 403.

Secure storage

Never put a private API key in browser-side JavaScript, a NEXT_PUBLIC_ variable, a public repository, a mobile application bundle, or frontend build configuration. Use a server, serverless function, or trusted backend and keep the key in its secret manager.

Node.js

const response = await fetch(`${process.env.IVORLEAF_API_BASE_URL}/v1/api/usage/status`, {
  headers: { Authorization: `Bearer ${process.env.IVORLEAF_API_KEY}` },
});

Python

import os
import requests

response = requests.get(
    f"{os.environ['IVORLEAF_API_BASE_URL'].rstrip('/')}/v1/api/usage/status",
    headers={"Authorization": f"Bearer {os.environ['IVORLEAF_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()

Key lifecycle

Keys can carry org_id, owner, plan, allowed_clients, expires_at, revocation status, and request/session/workflow limits. Unknown or malformed keys return 401. Revoked, inactive, expired, or disallowed-client keys return 403.

For production, use a separate key per integration environment where onboarding supports it, restrict clients, rotate through the onboarding/support process, and monitor GET /v1/api/usage/status. The public API intentionally does not expose administrative key-management routes.

Get a key

Request API access. The portal does not pretend to provide self-service key creation while onboarding is manual.