# Autenticación

> Autentica las peticiones con tokens owf_, entiende los roles y limita un token a una zona, a un cliente o a purgar la caché.

Cada petición a la API lleva un token de API en la cabecera `Authorization`. Los tokens empiezan por `owf_` y solo se muestran una vez, al crearlos; OpenWAF solo guarda su hash SHA-256.

```sh
curl https://dash.openwaf.dev/v1/orgs \
  -H "Authorization: Bearer $OPENWAF_TOKEN"
```

Un token ausente, no válido, caducado o revocado responde `401 unauthorized`.

## Crear un token

**Panel**

Abre **Tokens de API** en el menú de la organización, elige un nombre, un rol, si quieres una zona o un cliente, y la caducidad, y copia el secreto: no se vuelve a mostrar.

**API**

Llama a [Crear un token](https://developers.openwaf.dev/es/api/tokens/#create-token) con un token existente. El rol del nuevo token no puede ser mayor que el de quien lo crea.

```sh
curl -X POST "https://dash.openwaf.dev/v1/orgs/$OPENWAF_ORG/tokens" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name": "ci-deploy", "role": "tech", "expires_in_days": 90}'
```


Los tokens caducan a los `expires_in_days` días (de 1 a 365, 90 por defecto). Un token se revoca con [Revocar un token](https://developers.openwaf.dev/es/api/tokens/#revoke-token); quitar a un miembro invalida también todos sus tokens.

## Roles

Cada miembro de una organización tiene un rol, y cada token tiene el suyo. El rol efectivo de un token es el menor de los dos, así que bajar el rol de un miembro baja también el de sus tokens.

| Rol | Puede |
|---|---|
| `owner` | Todo, también dar o quitar el rol `owner`. Una organización siempre conserva al menos un owner. |
| `admin` | Gestionar miembros, invitaciones, tokens, clientes, marca blanca y egress; leer la auditoría; todo lo que puede `tech`. |
| `tech` | Cambiar zonas: añadir y borrar zonas, registros, ajustes de borde, reglas, purgas de caché, certificados de origen. |
| `readonly` | Leer todo lo que el token puede ver. |

Cada operación de esta referencia indica el rol mínimo que necesita. **De toda la organización** significa que el token (y su miembro) no está limitado a una zona ni a un cliente.

## Limitar un token

| Límite | Campo | Efecto |
|---|---|---|
| Una zona | `zone_id` | El token solo ve y cambia esa zona; [Listar zonas](https://developers.openwaf.dev/es/api/zones/#list-zones) solo devuelve esa. |
| Un cliente | `client_id` | El token solo ve las zonas de ese [cliente](https://developers.openwaf.dev/es/api/clients/). Solo roles `tech` y `readonly`. |
| Solo purgar la caché | `purge_only` | El token solo puede purgar la caché de su zona ([Purgar la caché](https://developers.openwaf.dev/es/api/cache/#purge-cache) y [Listar purgas](https://developers.openwaf.dev/es/api/cache/#list-cache-purges)); cualquier otra ruta responde `403 token_scope`. Exige `zone_id`, sin cliente, rol `tech`. |

Una petición sobre una zona u organización que el token no puede ver responde `404 not_found`, igual que un recurso que no existe.

## Guardar los tokens con seguridad

- Guarda los tokens en un gestor de secretos o en variables de entorno (los SDK y la CLI leen `OPENWAF_TOKEN`), nunca en el código.
- Da a cada integración su propio token con el menor rol que necesite y, si se puede, limitado a una zona.
- Revoca los tokens que ya no uses; `last_used_at` en [Listar tokens](https://developers.openwaf.dev/es/api/tokens/#list-tokens) muestra cuándo se usó cada uno por última vez.