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

# Autenticación

> Cómo funcionan las claves de API de Ciarem: vinculadas a la organización, plan Scale o prueba gratuita, revocables al instante.

## Claves de API

* Las claves pertenecen a tu **organización**, no a una persona. Siguen funcionando si el compañero que las creó deja el equipo.
* El secreto empieza con `oak_` y se muestra **una sola vez** al crearlo. Ciarem guarda únicamente un hash: nadie, ni siquiera Ciarem, puede recuperar un secreto perdido.
* Envíalo como token bearer en cada solicitud:

```bash theme={null}
-H "Authorization: Bearer oak_TU_SECRETO"
```

## Requisito de plan

La API es parte del plan **Scale**, y está abierta durante la **prueba gratuita** para que puedas construir y probar tu integración antes de pagar. Una clave en prueba obtiene toda la API con un presupuesto menor — consulta los [límites de uso](/api-reference/errors-limits-pagination). `GET /v1/me` te dice en cuál estás: `"trial": true` mientras dura la prueba.

Cuando una clave es rechazada con `403`, el `detail` dice qué lo resuelve:

| `detail`                | Significado                                                                 | Qué hacer                                                                                                                                               |
| ----------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scale_plan_required`   | La organización está en un plan activo por debajo de Scale (Solo o Growth). | Sube a Scale en **Configuración → Facturación**. La misma clave empieza a funcionar en el momento en que cambia el plan — no necesitas una clave nueva. |
| `trial_expired`         | La prueba gratuita terminó sin un método de pago.                           | Suscríbete a Scale en **Configuración → Facturación**.                                                                                                  |
| `subscription_required` | La suscripción está cancelada, o suspendida por falta de pago.              | Vuelve a suscribirte, o liquida el saldo pendiente.                                                                                                     |

## Revocación

Revoca una clave en cualquier momento en **Configuración → Claves de API**. La revocación es **inmediata**: la siguiente solicitud con ese secreto falla con `401`. Los administradores pueden crear tantas claves como necesiten — una por integración es un buen hábito, y la fecha de **último uso** de cada clave te ayuda a detectar las que puedes retirar.

## Buenas prácticas

* Guarda los secretos en tu gestor de secretos o variables de entorno — nunca en el código ni en aplicaciones del lado del cliente.
* La API es de servidor a servidor: no la llames desde un navegador o una app móvil donde la clave quedaría expuesta.
* Rota creando una clave nueva, migrando tu integración y revocando después la antigua.