What an API key does

The AILP API key authenticates every call your product makes to /assess and /assess/stream. The client sends it as the Airta-Api-Key header; the server rejects any request without it (HTTP 400). Pair it with a Airta-Program-Id to route logs into the right program.

Who can manage keys?

Only company owners and admins see the API Keys page. Members and viewers can still use keys that have been issued to them but cannot create, revoke, or list them on the dashboard.

Creating a key

Go to API Keys and click Create key.
Fill in:
- Name — required. Use something descriptive like "chatbot-prod — 2026 Q2" or "CI pipeline". It's what you'll see in the list when rotating.
- Expires at (optional) — a future date when the key stops working. Strongly recommended for production keys; AILP will simply reject requests after the timestamp.
- Program scope (optional) — restrict the key to a single program. Recommended: an attempt to ingest into any other program is rejected with 403, even when the caller owns that program. Leave unset to allow all programs in your company.
Submit. The plaintext key is shown exactly once. Copy it immediately into your secret manager — the dashboard only stores a hash from this point on.

Storing keys safely

Server environments — set AILP_API_KEY via your host's secrets manager (systemd credentials, Kubernetes secrets, AWS Secrets Manager, Vercel env vars, etc.). Never commit keys to the repo.
Browser / SPA environments — API keys are intended for server-to-server use. If you need to call AILP from a browser, proxy through your own backend so the key never leaves the server; never embed a production server key in NEXT_PUBLIC_AILP_API_KEY / VITE_AILP_API_KEY.
For sensitive workloads, call AILP from a server route or proxy rather than exposing the key to the browser at all.

Rotating a key safely

The simplest, zero-downtime rotation is the overlap pattern:

Create a new key with a meaningful name (e.g. include the quarter or rotation reason).
Deploy the new key to your application's secret store and roll out.
Verify assessments are flowing using the new key (check Consumer Log Analysis for recent entries).
Revoke the old key from the API Keys list.

Setting an expiry date on new keys turns rotation into a recurring reminder — the key automatically stops working on its expiry, and you can plan the overlap around it.

Revoking a compromised key

If a key may have leaked (exposed in logs, committed to a public repo, or sent to the wrong environment), revoke it immediately from the API Keys list. Revocation is instant — further requests using that key are rejected at the ingress layer. Create a replacement before or after revoke depending on whether you can tolerate brief assessment gaps.

Reviewing usage

Each key in the list shows its name, status (active / inactive), expiry date, and when it was last used. Inactive keys with no recent use are safe candidates for cleanup during quarterly key reviews.

Troubleshooting

Symptom	Likely cause
400 — `Missing required header(s): Airta-Api-Key`	The client didn't send the key. Verify `apiKey` / `AILP_API_KEY` is loaded.
401 / 403 on `/assess`	Key was revoked or has expired — rotate it from the dashboard.
403 — `API key is not scoped to this program`	The key was created with a program scope that doesn't match the `Airta-Program-Id` you're sending. Use a matching key or create an unscoped one.
Key works locally but not in production	Different environment, different key — confirm the production secret manager has the correct `AILP_API_KEY` and that it hasn't been revoked.

For credential handling in code, see AILP client authentication and credentials.