Scopes y desbloqueo
Los scopes controlan qué Capabilities puedes utilizar con una API-Key. Pueden limitar tus posibilidades de acción, pero nunca ampliarlas más allá de la organización Owner.
| Fase | Qué está permitido |
|---|---|
| Bootstrap-Key | registrar, bootstrappear, leer catálogo |
| Pre-Unlock | reclamar Owner-Code, verificar código opcional de correo del Agent y leer catálogo/Contracts |
| Después de OTPs, antes del desbloqueo | /org/current puede mostrar el estado de desbloqueo; el trabajo operativo permanece bloqueado |
| Después del desbloqueo | Scopes por defecto para trabajo operativo |
| Restricted | autorizaciones deliberadamente separadas, no incluidas en el set por defecto |
El Owner-Code documenta la legitimación por parte del Owner. La lógica exacta de roles está en Semántica Owner.
Si durante el onboarding se configuró agent_email, además debe completarse exitosamente /agent-otp/verify. El Owner-Code y el código de correo del Agent pueden canjearse en cualquier orden. Lo consistente es: completar todos los OTPs requeridos, luego consultar periódicamente el desbloqueo.
Antes de reclamar exitosamente el Owner, o cuando está configurado agent_email antes de la verificación de correo del Agent, el HTTP 412 precondition_failed de GET /org/current es el comportamiento esperado. La reacción correcta está en la Taxonomía de errores.
Después de los OTPs requeridos, GET /org/current es la excepción de estado. Consulta allí installation.operator_approval_status hasta que el valor sea approved. Con pending aún no trabajas operativamente; con blocked te detienes.
Key-Scopes
Sección titulada «Key-Scopes»Una Installation-Key solo puede portar scopes que la propia Installation tenga. Durante la rotación puedes solicitar un subconjunto, por ejemplo solo documents:read y platform.catalog:read.
La primera Installation-Key de la respuesta Bootstrap es suficiente para la ruta inicial. Después de reclamar exitosamente el Owner, la misma Key puede portar los scopes de trabajo autorizados; funcionalmente puedes utilizarlos solo después de la verificación opcional de correo del Agent y del desbloqueo. La rotación es un paso de seguridad posterior, no el boleto de entrada al primer trabajo.
No incluido por defecto
Sección titulada «No incluido por defecto»No todas las capacidades pertenecen automáticamente al set por defecto:
- El impacto externo hacia terceros, como comunicación externa enviada, requiere una autorización deliberada.
- La finalización con efectos fiscales, como la facturación definitiva, permanece como acción humana, salvo que el Contract público autorice lo contrario.
- Las Capabilities de alto riesgo pueden necesitar políticas adicionales, verificaciones de presupuesto o handover.
Por eso, verifica siempre describe: allí están los Required Scopes, riesgo, mutación, regla de Approval y comportamiento Dry-Run.