# Tokens de API

> Los tokens de API actúan por el miembro que los crea, con un rol no superior al suyo, un alcance opcional por dominio o cliente y caducidad de 1 a 365 días.

Un token de API permite que un script, un pipeline de CI, la [CLI](https://developers.openwaf.dev/es/cli/) o un [asistente de IA](https://developers.openwaf.dev/es/mcp/) usen la API de
OpenWAF en tu nombre. Los tokens tienen la forma `owf_…` y se envían como token bearer:

```http
GET /v1/orgs HTTP/1.1
Host: dash.openwaf.dev
Authorization: Bearer owf_…
```

`GET /v1/orgs` devuelve la organización a la que pertenece el token, con su `id`: el `{org}` de todas las demás rutas
de la API.

## De qué se compone un token

| Propiedad | Valores | Notas |
|---|---|---|
| Nombre | 1–200 caracteres | Dónde se usa, por ejemplo «despliegue CI». |
| Rol | `owner`, `admin`, `tech`, `readonly` | Como mucho tu propio rol. Por defecto, tu rol. |
| Alcance | Toda la organización, un dominio o un cliente | Limita cada token a lo que necesita. |
| Caducidad | 1–365 días | 90 días por defecto. No hay tokens sin caducidad. |
| Solo purgar | Sí o no | El token solo puede purgar la caché de un dominio. |

El secreto se muestra **una sola vez**, al crear el token. OpenWAF solo guarda un hash y muestra un prefijo corto en la
lista de tokens. Si pierdes un token, revócalo y crea otro.

## Dueño y rol efectivo

Cada token pertenece al miembro que lo creó y nunca hace más de lo que ese miembro puede hacer **ahora**:

- Su rol efectivo es el menor entre el rol del token y el rol actual del miembro.
- Si el miembro está limitado a un cliente, el token también lo está.
- Si el miembro sale de la organización o se le quita, todos sus tokens se revocan.

Consulta [Rol efectivo](https://developers.openwaf.dev/es/fundamentals/organizations-and-roles/#effective-role).

## Alcances

- **Toda la organización**: todos los dominios de la organización, dentro del rol del token.
- **Un dominio**: el token solo ve esa zona. No puede añadir ni borrar dominios, gestionar clientes ni crear otros
  tokens.
- **Un cliente**: el token solo ve los dominios asignados a ese cliente y solo puede tener el rol `tech` o `readonly`.
  Los dominios que añada quedan asignados a ese cliente.
- **Solo purgar**: un token `tech` limitado a un dominio que solo puede llamar a la purga de caché de ese dominio, por
  ejemplo desde CI tras un despliegue. Cualquier otra llamada se rechaza con `403 token_scope`. Consulta
  [Caché](https://developers.openwaf.dev/es/cache/).

## Crear un token

**Panel**

Abre **Tokens de API › Crear token**. Escribe un nombre, elige el rol, el alcance y **Caduca en (días)**, y pulsa
**Crear token**. Copia el secreto del cuadro de diálogo: no se vuelve a mostrar.
**API**

```sh
curl -X POST "https://dash.openwaf.dev/v1/orgs/$ORG/tokens" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "despliegue CI", "role": "tech", "zone_id": "'"$ZONE"'", "expires_in_days": 90}'
```
La respuesta incluye `secret`. Usa `client_id` en vez de `zone_id` para limitar el token a un cliente, y
`"purge_only": true` junto con un `zone_id` para un token que solo purga.


Cualquier miembro puede crear tokens para sí mismo. Un token limitado a un dominio no puede crear tokens.

## Listar y revocar tokens

Los administradores de toda la organización ven en **Tokens de API** todos los tokens activos, con su alcance, quién
los creó, cuándo caducan y su último uso, y pueden revocar cualquiera. Cualquier token puede revocarse a sí mismo.

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

La revocación es inmediata. Los tokens caducados, revocados o desconocidos reciben `401 unauthorized`.

## Tokens creados por OAuth

Al conectar un asistente de IA al [servidor MCP](https://developers.openwaf.dev/es/mcp/) con OAuth, OpenWAF crea un token para esa conexión. Aparece en
**Tokens de API** con la etiqueta **App OAuth**; revócalo para desconectar la aplicación.

## Buenas prácticas

- Da a cada integración su propio token, con el rol más bajo y el alcance más estrecho que le basten.
- Guarda los tokens en un gestor de secretos o en una variable de entorno, nunca en un repositorio, un ticket ni en la
  línea de órdenes. La CLI los lee de `OPENWAF_TOKEN` o de un fichero indicado en `OPENWAF_TOKEN_FILE` (legible solo
  por ti).
- Prefiere caducidades cortas y rota los tokens antes de que caduquen.