Para llamar a la API de Qomni necesitas una clave de API: una cadena
secreta que identifica tu workspace, el producto al que llamas y el modo
(prueba o real). La envías en cada petición, en el header Authorization,
como bearer token:
Authorization: Bearer sk_agents_live_co1_8fK2…Qa91ZxUna clave vale para un solo producto. Con una clave de Agents puedes llamar a
https://api.qomni.ai/agents/v1 y a nada más. Si la API recibe una clave de
otro producto, la petición falla con 401 api_key_wrong_product.
Por qué una clave por producto
Cada producto de Qomni tiene su propia API, su propio consumo y su propia factura. Una clave por producto te da tres cosas:
- Acceso mínimo. Un sistema que crea llamadas recibe una clave de Agents y nada más. Si esa clave se filtra, el atacante no entra a tu cuenta ni a la app web.
- Revocación sin daño colateral. Revocas una clave y las demás siguen funcionando.
- Enrutado sin consultas. La clave lleva la celda donde viven tus datos. El edge lee el prefijo y envía la petición al lugar correcto sin buscar nada en una base de datos. Lo explica El edge y las celdas.
Anatomía de una clave
| Parte | Qué significa |
|---|---|
sk |
Una clave secreta (secret key). |
agents |
El producto para el que sirve. Hoy, agents. |
live / test |
Modo real o modo de prueba. |
co1 |
La celda donde viven los datos del workspace. No necesitas leerla. |
| 30 caracteres | El secreto en sí. |
| 6 caracteres finales | Un checksum. Una clave mal copiada se rechaza antes de llegar a ningún servidor (401 api_key_malformed). |
Modos: prueba y real
El modo no es un ajuste de tu cuenta: lo decide la clave que usas. Una clave
sk_agents_test_… trabaja sobre datos de prueba y no marca ningún número.
Una clave sk_agents_live_… trabaja sobre datos reales y se factura. Tu
código es el mismo en los dos casos; cambias la clave y nada más. Los detalles
están en Modo de prueba.
Cómo se guarda y se muestra
Qomni guarda sólo el hash de cada clave, nunca el texto. Por eso la clave completa se muestra una sola vez, al crearla. Después sólo verás su prefijo y sus últimos cuatro caracteres.
Si pierdes una clave, no hay forma de recuperarla: crea otra y revoca la
anterior. La revocación es inmediata: la siguiente petición con esa clave
falla con 401 api_key_invalid.
Sesiones en tiempo real
Un WebSocket abierto desde un navegador no puede enviar headers, así que no
puede llevar tu clave. Para eso existe la sesión: tu servidor la crea con su
clave por REST, recibe una url válida durante 60 segundos y se la entrega
al cliente. El cliente abre el socket con esa url. La clave nunca sale de
tu servidor. Lo haces paso a paso en
Habla con un agente en tiempo real.
Límites
- Una clave no es un usuario: no sirve para entrar a la app web ni para la API de identidad.
- Una clave no vale en otro producto (
401 api_key_wrong_product) ni en otra celda (421 wrong_cell). - Una clave de un workspace sin el producto activo responde
403 product_not_active, aunque la clave sea válida. - Una clave es de un modo: para pasar a producción creas una clave
live, no conviertes la de prueba.
Ver también
- Inicio rápido: crea una clave y haz tu primera llamada.
- Errores: cada código que puede devolver la autenticación.
- Límites de uso: cuántas peticiones acepta cada clave.