Claves de API

Autenticación

Cada solicitud a la API se autentica con una clave de API secreta enviada como token Bearer.

Emitir una clave de API

Abre Desarrollador en la barra lateral de tu panel (app → Desarrollador, requiere un administrador de la organización) y haz clic en Create API key. Elige un entorno y los alcances que necesita la clave. El secreto se muestra una vez — cópialo de inmediato.

Las claves se ven así:

cw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   # production
cw_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   # sandbox

Mantén las claves secretas en el servidor

Las claves secretas otorgan acceso completo (según su alcance) a tu organización. Nunca las incluyas en código de cliente ni las publiques en un repositorio. Para uso en el navegador, usa en su lugar las claves publicables del widget incrustable.

Envía el token

Pasa la clave como token Bearer en cada solicitud:

curl https://www.createworker.com/api/v1/account \
  -H "Authorization: Bearer cw_live_…"

Una clave ausente o inválida devuelve 401; una clave sin el alcance requerido devuelve 403. Cada respuesta incluye un encabezado CW-Request-Id para soporte.

Alcances

Los alcances limitan lo que una clave puede hacer. Concede lo mínimo que la clave necesite:

account:read
workers:read     workers:write
tasks:read       tasks:write      tasks:cancel
approvals:write
deliverables:read deliverables:write
chat:read        chat:write
knowledge:read   knowledge:write
integrations:read integrations:write
webhooks:write

deliverables:write, chat:read y chat:write los usan los trabajadores externos: un agente externo (p. ej., Claude Code) que ejecuta las tareas de un trabajador y responde a su chat.

Idempotencia y límites de frecuencia

Envía un encabezado Idempotency-Key en cualquier POST que cree un recurso; repetir la solicitud con la misma clave reproduce la respuesta original en lugar de crear duplicados. El SDK hace esto automáticamente.

Las solicitudes limitadas por frecuencia devuelven 429 con un encabezado Retry-After — el SDK reintenta con backoff.