Autenticación

Cada petición lleva una clave de API del workspace. No hay flujo OAuth de client credentials ni endpoint de usuario y contraseña.

Cabeceras

Las dos funcionan. Prefiere la forma bearer.

bash

Authorization: Bearer zfk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# o
x-api-key: zfk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Nunca llames a esta API desde el navegador. x-api-key está deliberadamente fuera de nuestra lista de cabeceras permitidas en CORS, así que una llamada desde el navegador falla en el preflight. No es un obstáculo que sortear: una clave que llega al navegador es una clave filtrada.

Formato de la clave

La clave empieza por zfk_ seguido de 32 bytes de CSPRNG en base64url. De nuestro lado solo guardamos un hash SHA-256, así que no podemos volver a mostrarte el secreto — aparece exactamente una vez, al crearla.

Respuestas de fallo

Toda credencial rechazada devuelve el mismo cuerpo. Clave ausente, malformada, desconocida, revocada y caducada son idénticas byte a byte, salvo el id de la petición.

json

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing credentials",
  "request_id": "req_01J..."
}

Es deliberado. Decir cuál de los cinco estados aplica permitiría enumerar claves válidas y detectar el instante exacto en que una se revoca. El motivo real queda en el registro de auditoría del workspace, donde el propietario puede leerlo.

Qué significa cada estado

Estado	Significado	Qué hacer
401	La credencial está ausente, malformada, es desconocida, fue revocada o caducó.	Revisa la clave; crea otra si fue revocada.
403 `FORBIDDEN`	La clave es válida, pero esta capacidad nunca está disponible para claves.	No hay nada que reintentar. Las rutas de cuenta personal y de administración interna están cerradas de forma permanente a las claves.
403 `INSUFFICIENT_SCOPE`	La clave es válida, pero este ámbito no fue concedido — o el rol de quien la creó dejó de tenerlo.	Concede el ámbito, o pide a un propietario que cree la clave.
429	Límite de uso.	Respeta el Retry-After.

La regla de autoridad

El permiso efectivo de una clave se recalcula en cada petición:

text

efectivo(clave) = ámbitos(clave)
                ∩ capacidades(rol de quien creó la clave)
                ∩ ámbitos que las claves pueden tener

Así, degradar a un miembro estrecha al instante todas las claves que creó, y ninguna clave lleva una capacidad que su creador nunca tuvo.

Rotación

Crea la clave nueva, despliégala, y solo entonces revoca la antigua. La revocación es inmediata y permanente — la fila se conserva, nunca se borra, para que el registro de lo que hizo esa clave le sobreviva.