API keys

Every request to the iLive REST API is authenticated with an API key. Keys belong to a single tenant account and carry the rate-limit tier assigned when the key was issued.

What a key looks like

iLive API keys are opaque bearer tokens that start with the iksk_ prefix followed by a long random suffix, for example:

iksk_live_9f2d8c1a4b6e7f3d2c5a8b9e0f1a2d3c4e5f6a7b8c9d0e1f

Treat the full string as a secret. Only the prefix and the last four characters are displayed in the tenant portal after creation.

How to get one

During the private beta, request keys from your iLive account manager or email support@iliveauth.com. Once the self-service tenant portal goes generally available it will be reachable at /portal, where account owners can mint, tag, and revoke keys without contacting support.

Using a key

Send the key as a bearer token on every request to /api/v2/*:

curl https://api.iliveauth.com/api/v2/collections \
  -H "Authorization: Bearer iksk_live_9f2d8c1a4b6e7f3d2c5a8b9e0f1a2d3c4e5f6a7b8c9d0e1f"

The header is mandatory — unauthenticated requests to the v2 surface are rejected outright. v1 liveness endpoints accept the same header on the managed-session routes.

Scope and isolation

• Each key is bound to exactly one tenant account. Collections, faces, and usage counters are scoped to that tenant.
• Rate limits (see Rate limits) are counted per key, not per tenant, so separate services on the same account can each have their own budget.
• Revoking one key has no effect on sibling keys on the same account.

Best practices

• One key per environment. Issue a distinct key for development, staging, and each production service. Never reuse a production key in a local dev shell.
• Rotate on a schedule. Plan for a 90-day rotation cadence at minimum, and faster for keys with broad access. See Rotating keys.
• Keep keys out of client bundles. The v2 API is server-to-server; shipping a key to a browser or mobile app exposes your whole tenant.
• Store in a secret manager. Environment variables injected from Vault, AWS Secrets Manager, GCP Secret Manager, or 1Password are fine. Plain .env files committed to git are not.

Managing your account

Portal users sign in to /portal with an email address and password. Two flows are available on the sign-in screen:

• Forgot password. Click Forgot password? on the login form, enter your email, and we will send a reset link that is valid for 30 minutes. The endpoint always reports success — it never reveals whether an email matches an existing account.
• Email verification. New tenant users created by your iLive contact receive a verification email. You must click the link (valid for 24 hours) before you can sign in. If the link expires, ask an admin to re-provision the account and a fresh email will be sent.

The same two flows exist on the internal admin console at /admin.

Authentication errors

See Error codes for the full list.