Manage API keys

API keys authenticate every request to the Qualia API. This guide shows you how to create keys, keep them safe, and replace one without downtime.

How keys work

• A key starts with qk_live_. Send it in the Authorization header: Authorization: Bearer qk_live_....
• Keys belong to your organization. Any active key can send signups and read every actor in the organization.
• Each key has its own rate limit of 60 requests per minute for the actor endpoints.
• The API Keys page shows when each key was last used.

Create a key

1. Open Settings → API Keys and select Create key.
2. Give the key a name that says where it runs, such as Production backend or Staging.
3. Select Create, then copy the key.

You can show a key again later with the eye icon on the API Keys page.

Use a separate key for each environment and integration. When you retire one of them, you can revoke its key without touching the others.

Test a key

Call GET /v1/ping to check a key without sending a signup:

curl https://qualia.so/v1/ping \
  -H "Authorization: Bearer $QUALIA_API_KEY"

A working key returns 200 OK with "ok": true and the IDs of your organization and key. A wrong or revoked key returns 401. The check uses no credits and does not count toward the rate limit. See Check an API key.

Keep keys secret

Treat a key like a password.

• Store it in an environment variable or a secrets manager. Never commit it to source control.
• Use it only in server-side code. Never ship it in a browser bundle or a mobile app.
• If a key leaks, revoke it right away and create a new one.

Rotate a key without downtime

1. Create a new key.
2. Test the new key, then deploy it to your servers.
3. Check the Last used column on the API Keys page. Wait until the new key shows recent use and the old key's time stops changing.
4. Revoke the old key.

The TypeScript SDK calls its auth function before every request, and the function can be async. If it reads the key from a secrets manager, a rotated key takes effect without a restart.

Revoke a key

On the API Keys page, open the More menu next to the key, select Revoke, and confirm. Revoking takes effect immediately and cannot be undone. Requests that use a revoked key get 401 Unauthorized.

Next steps

• Handle errors and rate limits. What a 401 or 429 means and how to recover.
• API overview. Authentication and other API basics.