---
title: Autenticación
description: Cómo autorizar las solicitudes a la API de Clipia — la clave de API, tres formas de cabecera, claves de producción y de prueba, permisos de la clave y cómo guardarla de forma segura.
icon: KeyRound
---

Cada solicitud a `/v1/*` se autoriza con una clave de API. La clave se crea en la Developer Console, se muestra una sola vez, está vinculada a su cuenta y cobra los créditos de su saldo. La cabecera recomendada es `Authorization: Bearer clipia_live_…`.

## Formas de cabecera [#header-forms]

Puede enviar la clave de cualquiera de estas tres maneras. El servidor acepta todas, así que elija la que más le convenga.

<Tabs items={['Bearer', 'Key', 'X-Api-Key']}>
<Tab value="Bearer">

```bash
curl https://api.clipia.ai/v1/account \
  -H "Authorization: Bearer $CLIPIA_KEY"
```

</Tab>
<Tab value="Key">

```bash
curl https://api.clipia.ai/v1/account \
  -H "Authorization: Key $CLIPIA_KEY"
```

</Tab>
<Tab value="X-Api-Key">

```bash
curl https://api.clipia.ai/v1/account \
  -H "X-Api-Key: $CLIPIA_KEY"
```

</Tab>
</Tabs>

| Forma | Cabecera | Nota |
|------|--------|------|
| Bearer | `Authorization: Bearer …` | recomendada; solo acepta claves que empiezan por `clipia_` |
| Key | `Authorization: Key …` | esquema alternativo; la palabra `Key` no distingue mayúsculas de minúsculas |
| X-Api-Key | `X-Api-Key: …` | si prefiere una cabecera dedicada |

## Claves de producción y de prueba [#live-and-test-keys]

El prefijo de la clave determina el entorno. Se elige al crear la clave.

| Prefijo | Entorno | Comportamiento |
|--------|-------------|-----------|
| `clipia_live_…` | producción | generación real, se cobran créditos |
| `clipia_test_…` | entorno de pruebas | un ejemplo predefinido al instante; el coste se calcula, pero no se cobra |

Para pasar del entorno de pruebas a producción, basta con cambiar la clave, sin modificar el código. Consulte [Entorno de pruebas](/es/docs/getting-started/sandbox) para obtener más información.

<Callout type="warn" title="Las claves de producción requieren créditos comprados">
La generación con una clave `clipia_live_` está disponible para las cuentas que hayan comprado créditos al menos una vez. Sin una compra, la solicitud devuelve `402` con el código `insufficient_credits`. Las claves de prueba (`clipia_test_`) funcionan sin pago.
</Callout>

## Obtener una clave [#getting-a-key]

1. Abra la [Developer Console](/es/developer) y vaya a la pestaña **API Keys**.
2. Haga clic en **Create key**, asígnele un nombre (hasta 100 caracteres) y elija el entorno: producción o prueba.
3. Copie la clave y el **secreto de firma de webhooks**. Ambos se muestran una sola vez.

Una cuenta puede tener hasta 20 claves activas. Una vez alcanzado el límite, crear una clave devuelve `400` con el mensaje `api_key_limit_reached`: revoque una clave que ya no necesite y cree una nueva.

<Callout type="warn" title="La clave es un secreto del lado del servidor">
No coloque nunca la clave en un navegador, una aplicación móvil, un paquete de frontend o un repositorio público. Guárdela en un gestor de secretos o en variables de entorno del servidor. Si una clave se filtra, revóquela en la consola y cree una nueva.
</Callout>

## Permisos de la clave [#scopes]

Cada clave se crea con los permisos `generate` y `read`. Los permisos no se eligen al crear la clave.

| Permiso | Qué permite |
|------------|----------------|
| `generate` | crear generaciones (`POST /v1/models/{model}`) y el chat con LLM de [AI Gateway](/es/docs/llm-gateway) (`POST /v1/chat/completions`) |
| `read` | reservado; hoy no habilita nada adicional |

- No necesita una clave aparte para el chat con LLM: `generate` lo cubre. La generación de contenido multimedia y las llamadas a LLM consumen créditos del mismo saldo.
- Cualquier clave válida puede leer el estado y el resultado de sus propias generaciones.
- El catálogo de modelos (`GET /v1/models`), la estimación del coste y el saldo (`GET /v1/account`) no requieren permisos adicionales.
- Una solicitud sin el permiso necesario devuelve `403 insufficient_scope`.

<Callout type="error" title="Clave rechazada">
Si la clave falta, es incorrecta o ha sido revocada, el servidor devuelve `401 invalid_api_key`. Compruebe el prefijo del entorno y que la clave se envía en una de las tres cabeceras. El esquema `Bearer` solo acepta claves que empiezan por `clipia_`.
</Callout>