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:
Authorization: Bearer sk_agents_live_co1_8fK2…Qa91ZxA 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.
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 explains it.
Anatomy of a key
| Part | What it means |
|---|---|
sk |
A secret key. |
agents |
The product it works for. Today, agents. |
live / test |
Live mode or 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.
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
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.
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
livekey, you do not convert the test one.
See also
- Quickstart: create a key and make your first call.
- Errors: every code authentication can return.
- Rate limits: how many requests each key accepts.