---
title: "API keys y autenticación"
description: "Qué es una clave de API de Qomni, qué partes tiene y por qué cada clave vale para un solo producto, un solo modo y una sola celda."
version: "es"
---

> 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 y autenticación

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:

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

Una 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`.

> **Caution**
>
> Las claves son para tu servidor. **Nunca las pongas en un navegador ni en una
> app móvil**: cualquiera podría leerlas. Para hablar con un agente desde un
> navegador, usa una [sesión en tiempo real](#sesiones-en-tiempo-real).

## 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](/es/concepts/edge/).

## Anatomía de una clave

<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>

| 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](/es/concepts/test-mode/). |
| `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](/es/concepts/test-mode/).

## 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 {#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](/es/agents/realtime/).

## 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](/es/get-started/quickstart/): crea una clave y haz tu primera llamada.
- [Errores](/es/concepts/errors/): cada código que puede devolver la autenticación.
- [Límites de uso](/es/concepts/rate-limits/): cuántas peticiones acepta cada clave.

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