Getting started

Authentication

How API keys work, where they belong, and what to do when one leaks.

Every request carries a key. The key identifies a workspace, and everything the request can reach belongs to that workspace — its assistants, its knowledge, its conversations, and nothing else.

The header#

HTTP
Authorization: Bearer zv_live_8Kd2mQx7pRvN4tLc9YbA3sHfW6jE1nZgU5oX0iTyMqB

X-Api-Key is accepted as an alternative, for clients where setting an Authorization header is awkward.

HTTP
X-Api-Key: zv_live_8Kd2mQx7pRvN4tLc9YbA3sHfW6jE1nZgU5oX0iTyMqB

Send one or the other. If both are present, Authorization wins.

Creating a key#

Studio → API → Keys → Create key.

Give it a name that identifies where it runs — Production backend, Staging, Ops scripts. When you are looking at a usage spike or revoking after a laptop is lost, the name is the only thing that tells you what you are about to break.

The key is shown once, at creation.

We store a hash of it, not the key. That is deliberate: there is no request we could ever make that needs the original back, so keeping it would be storing a secret for no purpose. It also means nobody at Zeevaa can read your key, and a database breach does not hand anyone a working one.

If you lose it, create another and revoke the old one. There is no recovery, and that is the point.

Where a key belongs#

On your server. In an environment variable. Nowhere else.

Terminal
# .env — and .env is in .gitignore
ZEEVAA_API_KEY=zv_live_…
TypeScript
const response = await fetch("https://studio.zeevaa.ai/api/v1/assistants", {
  headers: { Authorization: `Bearer ${process.env.ZEEVAA_API_KEY}` },
});

Warning

Never put a key in browser JavaScript, a mobile app binary, a public repository, or a URL query string. All four are readable by someone who is not you. URLs are the sneakiest of the four — they end up in server logs, browser history, and Referer headers sent to third parties.

If a page needs to reach the API, route it through your own backend. The Next.js guide shows the whole pattern.

One key or several#

One key is enough to start, and one key reaches every endpoint — assistants today, and everything the API grows into later. You will not need a second key to use a new feature.

Use more than one when you want to be able to revoke part of your estate without taking down the rest:

  • Per environment — production, staging and local, so rotating one leaves the others running
  • Per system — the web app, the nightly sync, the support tool, so a usage spike names its own cause
  • Per customer, if you resell — so offboarding is one revocation

Revoking#

Studio → API → Keys → Revoke.

Revocation takes effect on the next request. Anything already in flight finishes; anything after that gets 401.

A revoked key is not deleted. It stays in your key list, marked revoked, and your usage history and request logs keep resolving through it — otherwise revoking a key would erase the evidence of whatever made you revoke it.

Rotating#

There is no in-place rotation, because a key that changes value underneath a running deployment is an outage. Rotate by overlapping instead:

  1. Create a new key
  2. Deploy it to whatever uses the old one
  3. Confirm traffic has moved — API → Usage, grouped by key
  4. Revoke the old key

Step 3 is the one people skip. A scheduled job that runs weekly may not have touched the new key yet when you revoke the old one.

Restricting a key#

A key can optionally be limited to specific assistants. A restricted key returns 403 for anything else, and does not list the assistants it cannot reach.

Useful when a key lives somewhere you do not fully control — a partner's system, a customer's deployment, a script on a shared machine.

If a key leaks#

  1. Revoke it first. Not after you have worked out what happened — the investigation is easier when the key is already dead.
  2. Create a replacement and deploy it.
  3. Check API → Usage and API → Logs for requests you cannot account for: unfamiliar times, unexpected assistants, unusual volume.
  4. Read the conversations. Assistant history shows every session a key opened, so you can see what was actually said.

What a key cannot do#

An API key is not an admin credential. It cannot:

  • Create, edit or delete assistants
  • Read or change your provider credentials
  • Upload or delete knowledge
  • Create or revoke other API keys
  • Reach any workspace but its own

Everything an API key can do is a read or a conversation. Configuration stays in Studio, behind a human sign-in.

Next#

  • Errors — what a failed request looks like
  • Rate limits — what you get, and what happens at the ceiling