---
title: "API keys and authentication"
description: "What a Qomni API key is, what parts it has and why each key works for a single product, a single mode and a single cell."
version: "en"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.qomni.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys and authentication

To call the Qomni API you need an **API key**: a secret string that identifies
your workspace, the product you call and the mode (test or live). You send it
in every request, in the `Authorization` header, as a bearer token:

```http
Authorization: Bearer sk_agents_live_co1_8fK2…Qa91Zx
```

A key works for a single product. With an Agents key you can call `https://api.qomni.ai/agents/v1` and
nothing else. If the API receives a key from another product, the request
fails with `401 api_key_wrong_product`.

> **Caution**
>
> Keys are for your server. **Never put them in a browser or in a mobile app**:
> anyone could read them. To talk to an agent from a browser, use a
> [realtime session](#sesiones-en-tiempo-real).

## Why one key per product

Each Qomni product has its own API, its own usage and its own invoice. One key
per product gives you three things:

- **Least access.** A system that creates calls gets an Agents key and nothing
  else. If that key leaks, the attacker gets into neither your account nor the
  web app.
- **Revocation without collateral damage.** You revoke one key and the others
  keep working.
- **Routing without lookups.** The key carries the cell where your data lives.
  The edge reads the prefix and sends the request to the right place without
  looking anything up in a database. [The edge and cells](/concepts/edge/) explains it.

## Anatomy of a key

<div class="q-key not-prose">
  <span data-part="type">sk</span>{"_"}<span data-part="product">agents</span>{"_"}<span data-part="mode">live</span>{"_"}<span data-part="cell">co1</span>{"_8fK2…"}<span data-part="check">Qa91Zx</span>
</div>

| Part | What it means |
|---|---|
| `sk` | A secret key. |
| `agents` | The product it works for. Today, `agents`. |
| `live` / `test` | Live mode or [test mode](/concepts/test-mode/). |
| `co1` | The cell where the workspace's data lives. You do not need to read it. |
| 30 characters | The secret itself. |
| 6 final characters | A checksum. A badly copied key is rejected before it reaches any server (`401 api_key_malformed`). |

## Modes: test and live

The mode is not an account setting: the key you use decides it. A `sk_agents_test_…` key
works on test data and never dials a number. A `sk_agents_live_…` key works on real data
and is billed. Your code is the same in both cases; you change the key and
nothing else. The details are in [Test mode](/concepts/test-mode/).

## How it is stored and shown

Qomni stores only the hash of each key, never the text. That is why the full
key is shown **only once**, when you create it. After that you only see its
prefix and its last four characters.

If you lose a key, there is no way to recover it: create another one and
revoke the old one. Revocation is immediate: the next request with that key
fails with `401 api_key_invalid`.

## Realtime sessions {#sesiones-en-tiempo-real}

A WebSocket opened from a browser cannot send headers, so it cannot carry your
key. That is what the session is for: your server creates it with its key over
REST, receives a `url` valid for 60 seconds and hands it to the client. The
client opens the socket with that `url`. The key never leaves your server.
You do it step by step in [Talk to an agent in realtime](/agents/realtime/).

## Limits

- A key is not a user: it does not sign you in to the web app or the identity
  API.
- A key does not work in another product (`401 api_key_wrong_product`) or in another cell
  (`421 wrong_cell`).
- A key from a workspace without the product enabled responds `403 product_not_active`, even
  if the key is valid.
- A key belongs to one mode: to go to production you create a `live` key,
  you do not convert the test one.

## See also

- [Quickstart](/get-started/quickstart/): create a key and make your first call.
- [Errors](/concepts/errors/): every code authentication can return.
- [Rate limits](/concepts/rate-limits/): how many requests each key accepts.

Source: https://docs.qomni.ai/concepts/authentication/index.mdx
