Tokens de API de Orbit y la REST API

Los tokens de API permiten que un script, una canalización de CI o tus propias herramientas impulsen Orbit sin una sesión del navegador: desencadena implementaciones, reporta resultados de verificación de CI, descarga artefactos de compilación, gestiona trabajos cron y mucho más, todo autenticado con un token Bearer que estableces tú mismo.

Dónde viven los tokens

Abre Orbit y elige Tokens en la navegación de nivel superior. La página se titula API Access Tokens y establece su propia regla desde el principio: los tokens se muestran una sola vez en la creación.

La documentación completa del endpoint está a un clic de distancia. La tarjeta API Reference tiene un botón View docs que abre la referencia dentro del panel para cada endpoint de Orbit.

Crear un token

1. Haz clic en New token.
2. Dale un Token name. Nómbralo según la cosa que lo usará, por ejemplo el flujo de CI, para que el inventario sea legible más adelante.
3. Elige sus Scopes.
4. Opcionalmente establece una Expiry. Déjalo en blanco para un token que no expire.
5. Haz clic en Create token.

El token sin procesar se muestra una sola vez, bajo un encabezado One-time reveal, con un botón de copiar. Pégalo directamente en tu almacén de secretos de CI. No hay forma de verlo nuevamente: solo se almacena un hash SHA-256 del token, por lo que ni siquiera Kapsule puede recuperarlo para ti.

Una cuenta puede contener hasta 20 tokens activos. La creación de un vigésimo primero es rechazada con un mensaje que te dice que revokes uno existente primero.

Scopes

Los scopes son todo el punto de los tokens: cada uno lleva solo los permisos que le diste.

Un nuevo token usa por defecto deploy:write e project:read, que es lo que necesita una canalización de implementación y nada más.

Otorga el conjunto más pequeño que haga el trabajo. Un token que solo necesita reportar un resultado de CI no necesita project:write. Un script de monitoreo de solo lectura no necesita ningún scope de escritura. Cada endpoint en la referencia enumera el scope mínimo que requiere.

Usar un token

La autenticación es un encabezado Bearer contra la base de API, https://kapsulehost.com:

curl -X POST https://kapsulehost.com/api/orbit/$ORBIT_PROJECT_ID/deployments \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main"}'

La página Tokens lleva un fragmento CI/CD usage listo para usar y un flujo de trabajo iniciador GitHub Actions. El iniciador se guarda como .github/workflows/orbit-deploy.yml y necesita dos secretos de repositorio, ORBIT_TOKEN e ORBIT_PROJECT_ID. Copia ambos de la página en lugar de transcribirlos.

Lo que cubre la API

La referencia dentro del panel documenta cada área con sus parámetros y scope requerido:

• Deployments: desencadena una implementación, opcionalmente en una rama nombrada, opcionalmente programada para un tiempo futuro entre cinco minutos y treinta días en adelante, con una nota de hasta 500 caracteres. La lista admite búsqueda difusa en commit, mensaje, rama y autor, además de filtros en rama, estado y entorno, con paginación de cursor de hasta 100 resultados por página.
• Deployment checks: registra una puerta de calidad al inicio de tu trabajo de CI y luego reporta el resultado cuando finaliza. Una verificación required que falla mueve la implementación a FAILED y revierte el entorno a la implementación anterior exitosa, que es cómo haces que tu propia suite de pruebas sea una verdadera puerta de implementación.
• Branch protection: reglas de patrón glob que bloquean implementaciones automáticas hasta que pasen las verificaciones requeridas y, opcionalmente, alguien las apruebe. Hasta diez reglas por proyecto.
• Build artifacts: obtén una URL de descarga pre-firmada para la salida compilada de una implementación exitosa. La URL es válida durante quince minutos.
• Project transfer: inicia, cancela y verifica el estado de una transferencia a otra cuenta. Consulta Transferring an Orbit Project.
• Cron jobs: lista, crea, actualiza, elimina, desencadena y lee el historial de ejecución. Consulta Orbit Cron Jobs.
• Timeline annotations: crea y gestiona anotaciones de incidente, versión, hito, nota e indicador. Consulta Orbit Timeline Annotations.
• Status page: lee y escribe la configuración de la página de estado pública. Consulta Orbit Status Page.
• Edge functions: lista, crea, actualiza e implementa manejadores perimetrales. Consulta Orbit Edge Functions.

La autenticación de sesión desde el panel funciona junto con los tokens Bearer, por lo que un endpoint que puedes llamar desde tu navegador generalmente también puede ser llamado desde un script.

Turbo Remote Cache

La página Tokens también lleva una tarjeta Remote Build Cache. Implementa el Protocolo de Caché Remoto de Turborepo, permitiendo que un monorepo comparta cachés de compilación entre ejecuciones de CI y máquinas de desarrolladores.

Habilítalo en la tarjeta, copia el token que genera, y establécelo junto con tu ID de cuenta como TURBO_TEAM en tu entorno de CI. Se aceptan artefactos de hasta 150 MB cada uno. La tarjeta también ofrece Rotate token y Disable.

Si el CI de tu monorepo pasa la mayor parte del tiempo recompilando paquetes que no han cambiado, esta es la cosa de mayor valor en la página.

Gestionar el inventario

La Token inventory enumera cada token activo con:

• Cuándo fue Created.
• Cuándo fue Last used, o Never.
• Cuándo Expires, con un distintivo expired una vez que lo haya hecho.

La columna Last used es la que se debe auditar. Un token que nunca ha sido usado está mal configurado u olvidado, y de cualquier manera es una credencial que está sin hacer nada. La propia sugerencia de la página lo dice claramente: revoca cualquier cosa que no reconozcas.

Revocar un token

Haz clic en el control de revocación en la fila. La confirmación es explícita: todo lo que se autentica con ese token pierde acceso inmediatamente, y esto no se puede deshacer.

Revoca cuando se retira una canalización, cuando alguien con acceso a tus secretos de CI se va, o en el momento en que sospechas que un token se ha filtrado. No hay revocación parcial ni período de gracia, que es exactamente lo que quieres en caso de filtración.

Solución de problemas

401 Unauthorized. El encabezado es incorrecto o el token ha sido revocado o ha expirado. Verifica que el encabezado sea Authorization: Bearer <token> con un solo espacio, y que tu secreto de CI no tenga una nueva línea final.

403 Forbidden. El token es válido pero carece del scope para ese endpoint. La referencia enumera el scope mínimo por endpoint. Los scopes se fijan en la creación, así que crea un nuevo token con el conjunto correcto.

429 on creation. Estás en el límite de veinte tokens. Revoca algo del inventario.

The artifact URL stops working. Las URLs pre-firmadas duran quince minutos. Solicita una nueva en lugar de almacenar la URL.

A scheduled deployment is rejected. El tiempo programado debe estar entre cinco minutos y treinta días en el futuro.

Dónde ir a continuación

• Deploying Your Project para lo que realmente hace una implementación desencadenada.
• Orbit Deployment Pipeline para ver qué puertas cumplirán tus implementaciones de API.
• Orbit Plan Limits para lo que incluye tu plan.