Autenticación

La API usa API keys. Creas una en el panel (se muestra una sola vez, ver API keys) y la envías en cada petición como token Bearer:

curl "https://zappio.cloud/api/v1/api-key" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY"

{
  "data": {
    "id": "key_01EXAMPLEEXAMPLEEXAMPLE00",
    "name": "Backend",
    "scopes": ["instances:read", "messages:send"],
    "workspace": { "id": "ten_01EXAMPLEEXAMPLEEXAMPLE00", "name": "Acme" }
  }
}

GET /api-key es la forma más rápida de comprobar que una clave funciona: devuelve su nombre, sus permisos y el espacio de trabajo al que pertenece. No necesita ningún permiso en particular.

Permisos (scopes)

Una clave pertenece a un espacio de trabajo y lleva una lista de permisos, llamados scopes. Cada operación exige el suyo; si falta, la API responde 403 INSUFFICIENT_SCOPE.

Scope	Permite
instances:read	Listar y consultar instancias; listar los grupos de una instancia.
instances:write	Crear, renombrar, conectar, desconectar, cerrar sesión y eliminar instancias; obtener el QR de vinculación.
messages:read	Listar y consultar mensajes; descargar multimedia.
messages:send	Enviar mensajes.
webhooks:read	Listar y consultar webhooks y sus entregas.
webhooks:write	Crear, editar, eliminar y rotar el secreto de webhooks; enviar pruebas; reintentar entregas.

La referencia indica el scope de cada operación en su sección de autorización.

Errores de autenticación

Respuesta	Código	Cuándo
401	UNAUTHENTICATED	No llegó el header Authorization: Bearer.
401	INVALID_API_KEY	La clave no existe o fue revocada.
403	INSUFFICIENT_SCOPE	La clave no tiene el scope de la operación.
403	WORKSPACE_SUSPENDED	El espacio de trabajo está suspendido.
400	WORKSPACE_MISMATCH	Enviaste X-Zappio-Workspace con el id de otro espacio de trabajo.

Con una API key no necesitas el header X-Zappio-Workspace (lo usa el panel). Si lo envías, debe coincidir con el espacio de trabajo de la clave.

Buenas prácticas

• Guarda la clave en una variable de entorno o en un gestor de secretos, nunca en el código ni en el navegador.
• Usa una clave por integración y dale solo los scopes que necesita.
• Si una clave se filtra, revócala en el panel y crea otra.

Más detalle en API keys.