Tokens de API

Crea, lista y revoca los tokens owf_ que autentican las peticiones a la API, la CLI y el servidor MCP.

Los tokens de API (owf_…) autentican la API, los SDK, la CLI y el servidor MCP. Un token actúa con el rol de su miembro, limitado al rol del propio token y, si se quiere, a una zona o a un cliente. Consulta Autenticación.

Operación	Ruta
Listar tokens	`GET /v1/orgs/{org}/tokens`
Crear un token	`POST /v1/orgs/{org}/tokens`
Revocar un token	`DELETE /v1/orgs/{org}/tokens/{id}`

Listar tokens

GET /v1/orgs/{org}/tokens

Lista los tokens de API activos de la organización, nunca sus secretos. prefix ayuda a reconocer cada uno y last_used_at dice cuándo se usó por última vez.

Rol necesario: admin o superior. De toda la organización.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`org`	ruta	string (uuid)	Sí	Id de la organización. Cada ruta comprueba que es la del token (si no, `404`).

Respuesta

200: Devuelve items, un array de APIToken.

Campo	Tipo	Descripción
`items[].id`	string (uuid)	Id.
`items[].org_id`	string (uuid)	Id de la organización.
`items[].zone_id`	string (uuid)	Id de la zona.
`items[].user_id`	string (uuid)	Id de usuario del miembro.
`items[].name`	string	Nombre.
`items[].role`	string	Rol. Uno de `owner`, `admin`, `tech`, `readonly`.
`items[].prefix`	string	Primeros caracteres del secreto, para reconocerlo.
`items[].purge_only`	boolean	Solo puede purgar la caché de su zona.
`items[].created_by`	string	Quién lo creó (actor).
`items[].created_at`	string (date-time)	Fecha de creación.
`items[].expires_at`	string (date-time)	Fecha de caducidad.
`items[].last_used_at`	string (date-time)	Último uso.
`items[].client_id`	string (uuid) o null	Cliente al que se limita el token (solo roles tech y readonly); null = toda la organización.

Ejemplo

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

import { OpenWAF } from "./openwaf";

const owf = new OpenWAF({ baseUrl: "https://dash.openwaf.dev" }); // token de OPENWAF_TOKEN
const result = await owf.listTokens();

from openwaf import OpenWAF

owf = OpenWAF(base_url="https://dash.openwaf.dev")  # token de OPENWAF_TOKEN
result = owf.list_tokens()

200

{
  "items": [
    {
      "id": "11111111-2222-4333-8444-555555555555",
      "org_id": "1e7c9a3b-5d2f-4b8a-9c6e-0f2a4b6c8d1e",
      "zone_id": "6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d",
      "user_id": "5b8e2a1c-7d3f-4a9e-b6c2-1e4d7f0a3b9c",
      "name": "ci-deploy",
      "role": "tech",
      "prefix": "owf_8Jx2",
      "purge_only": false,
      "created_by": "user:5b8e2a1c-7d3f-4a9e-b6c2-1e4d7f0a3b9c",
      "created_at": "2026-10-27T09:30:00Z",
      "expires_at": "2027-01-25T09:30:00Z",
      "client_id": null
    }
  ]
}

Crear un token

POST /v1/orgs/{org}/tokens

Crea un token de API para el propio miembro de quien llama. Sin role, el token recibe el rol de quien lo crea. Se puede limitar a una zona (zone_id), a un cliente (client_id) o a purgar la caché de su zona (purge_only). Consulta Limitar un token.

El secret (owf_…) solo se devuelve en esta respuesta: guárdalo enseguida.

Rol necesario: readonly o superior. El rol del nuevo token no puede ser mayor que el de quien lo crea. No disponible para tokens limitados a una zona.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`org`	ruta	string (uuid)	Sí	Id de la organización. Cada ruta comprueba que es la del token (si no, `404`).

Cuerpo de la petición

Tipo de contenido application/json.

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre. Como mucho 200 caracteres.
`role`	string	No	Rol del token; por defecto, el de quien lo crea (tech con purge_only). Uno de `owner`, `admin`, `tech`, `readonly`.
`zone_id`	string (uuid)	No	Limita el token a esa zona.
`expires_in_days`	integer	No	Por defecto `90`. De 1 a 365.
`purge_only`	boolean	No	Token que solo puede purgar la caché de su zona (POST cache/purge y GET cache/purges; cualquier otra ruta, MCP incluido, responde 403 token_scope). Exige zone_id, sin cliente; rol tech (por defecto). Por defecto `false`.
`client_id`	string (uuid)	No	Limita el token a las zonas de un cliente (solo roles tech y readonly). Una credencial limitada a un cliente solo emite tokens de su cliente.

Respuesta

201: Creado; secret se muestra una sola vez. Devuelve IssuedToken.

Campo	Tipo	Descripción
`id`	string (uuid)	Id.
`org_id`	string (uuid)	Id de la organización.
`zone_id`	string (uuid)	Id de la zona.
`user_id`	string (uuid)	Id de usuario del miembro.
`name`	string	Nombre.
`role`	string	Rol. Uno de `owner`, `admin`, `tech`, `readonly`.
`prefix`	string	Primeros caracteres del secreto, para reconocerlo.
`purge_only`	boolean	Solo puede purgar la caché de su zona.
`created_by`	string	Quién lo creó (actor).
`created_at`	string (date-time)	Fecha de creación.
`expires_at`	string (date-time)	Fecha de caducidad.
`last_used_at`	string (date-time)	Último uso.
`client_id`	string (uuid) o null	Cliente al que se limita el token (solo roles tech y readonly); null = toda la organización.
`secret`	string	Se muestra una sola vez; solo se guarda su SHA-256.

Errores

Estado	Descripción
`403`	El rol o los límites del token no lo permiten (`forbidden`).
`404`	No existe o el token no lo ve (`not_found`).

Ejemplo

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",
    "zone_id": "6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d",
    "expires_in_days": 90
  }'

import { OpenWAF } from "./openwaf";

const owf = new OpenWAF({ baseUrl: "https://dash.openwaf.dev" }); // token de OPENWAF_TOKEN
const result = await owf.createToken({
  body: {
    name: "ci-deploy",
    role: "tech",
    zone_id: "6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d",
    expires_in_days: 90
  }
});

from openwaf import OpenWAF

owf = OpenWAF(base_url="https://dash.openwaf.dev")  # token de OPENWAF_TOKEN
result = owf.create_token(
    body={
        "name": "ci-deploy",
        "role": "tech",
        "zone_id": "6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d",
        "expires_in_days": 90
    },
)

201

{
  "id": "11111111-2222-4333-8444-555555555555",
  "org_id": "1e7c9a3b-5d2f-4b8a-9c6e-0f2a4b6c8d1e",
  "zone_id": "6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d",
  "user_id": "5b8e2a1c-7d3f-4a9e-b6c2-1e4d7f0a3b9c",
  "name": "ci-deploy",
  "role": "tech",
  "prefix": "owf_8Jx2",
  "purge_only": false,
  "created_by": "user:5b8e2a1c-7d3f-4a9e-b6c2-1e4d7f0a3b9c",
  "created_at": "2026-10-27T09:30:00Z",
  "expires_at": "2027-01-25T09:30:00Z",
  "client_id": null,
  "secret": "owf_8Jx2…"
}

Revocar un token

DELETE /v1/orgs/{org}/tokens/{id}

Revoca un token; deja de valer al momento.

Rol necesario: admin o superior. De toda la organización, o cualquier rol para revocar el propio token de la petición.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`org`	ruta	string (uuid)	Sí	Id de la organización. Cada ruta comprueba que es la del token (si no, `404`).
`id`	ruta	string (uuid)	Sí	Id del recurso.

Respuesta

204: Revocado. Sin cuerpo.

Errores

Estado	Descripción
`404`	No existe o el token no lo ve (`not_found`).

Ejemplo

curl -X DELETE "https://dash.openwaf.dev/v1/orgs/$OPENWAF_ORG/tokens/11111111-2222-4333-8444-555555555555" \
  -H "Authorization: Bearer $OPENWAF_TOKEN"

import { OpenWAF } from "./openwaf";

const owf = new OpenWAF({ baseUrl: "https://dash.openwaf.dev" }); // token de OPENWAF_TOKEN
const result = await owf.revokeToken({
  id: "11111111-2222-4333-8444-555555555555"
});

from openwaf import OpenWAF

owf = OpenWAF(base_url="https://dash.openwaf.dev")  # token de OPENWAF_TOKEN
result = owf.revoke_token(id="11111111-2222-4333-8444-555555555555")

Tokens de API

#Listar tokens

#Parámetros

#Respuesta

#Ejemplo

#Crear un token

#Parámetros

#Cuerpo de la petición

#Respuesta

#Errores

#Ejemplo

#Revocar un token

#Parámetros

#Respuesta

#Errores

#Ejemplo

Listar tokens

Parámetros

Respuesta

Ejemplo

Crear un token

Parámetros

Cuerpo de la petición

Respuesta

Errores

Ejemplo

Revocar un token

Parámetros

Respuesta

Errores

Ejemplo