Un token de API permite que un script, un pipeline de CI, la CLI o un asistente de IA usen la API de OpenWAF en tu nombre. Los tokens tienen la forma owf_… y se envían como token bearer:
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.
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
techoreadonly. Los dominios que añada quedan asignados a ese cliente. - Solo purgar: un token
techlimitado 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 con403 token_scope. Consulta Caché.
Crear un token
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.
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.
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 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_TOKENo de un fichero indicado enOPENWAF_TOKEN_FILE(legible solo por ti). - Prefiere caducidades cortas y rota los tokens antes de que caduquen.