Token API Orbit e la REST API

I token API permettono a uno script, a una pipeline CI o ai tuoi strumenti di gestire Orbit senza una sessione browser: attivare deployment, segnalare risultati di controllo CI, scaricare artefatti di build, gestire job cron e molto altro, tutto autenticato con un token Bearer che definisci tu stesso.

Dove si trovano i Token

Apri Orbit e scegli Tokens dalla navigazione di primo livello. La pagina è intitolata API Access Tokens e espone subito la sua regola: i token vengono mostrati una sola volta al momento della creazione.

La documentazione completa dell'endpoint si trova a un click di distanza. La scheda API Reference ha un pulsante View docs che apre il riferimento in-panel per ogni endpoint di Orbit.

Creazione di un Token

1. Fai clic su New token.
2. Assegnagli un Token name. Dagli il nome della cosa che lo utilizzerà, ad esempio il workflow CI, così l'inventario sarà leggibile in seguito.
3. Scegli i suoi Scopes.
4. Facoltativamente imposta una Expiry. Lasciala vuota per un token che non scade.
5. Fai clic su Create token.

Il token grezzo viene visualizzato una sola volta, sotto un'intestazione One-time reveal, con un pulsante di copia. Incollalo direttamente nel tuo archivio di secret CI. Non c'è modo di vederlo di nuovo: solo un hash SHA-256 del token viene archiviato, quindi nemmeno KapsuleHost può recuperarlo per te.

Un account può contenere fino a 20 token attivi. La creazione di un ventunesimo viene rifiutata con un messaggio che ti dice di revocare prima un token esistente.

Scopes

Gli scopes sono il punto chiave dei token: ognuno porta solo i permessi che gli hai assegnato.

Un nuovo token di default ha deploy:write e project:read, cioè quello che serve a una pipeline di deployment e niente di più.

Concedi il set più piccolo che fa il lavoro. Un token che ha solo bisogno di segnalare un risultato CI non ha bisogno di project:write. Uno script di monitoraggio di sola lettura non ha bisogno di nessuno scope di scrittura. Ogni endpoint nel riferimento elenca lo scope minimo che richiede.

Utilizzo di un Token

L'autenticazione è un header Bearer contro la base 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 pagina Tokens include uno snippet CI/CD usage pronto all'uso e un workflow starter GitHub Actions. Lo starter viene salvato come .github/workflows/orbit-deploy.yml e ha bisogno di due secret del repository, ORBIT_TOKEN e ORBIT_PROJECT_ID. Copia entrambi dalla pagina piuttosto che trascriverli.

Cosa copre l'API

Il riferimento in-panel documenta ogni area con i suoi parametri e lo scope richiesto:

• Deployments: attivare un deploy, facoltativamente su un ramo denominato, facoltativamente programmato per un momento futuro tra cinque minuti e trenta giorni, con una nota di massimo 500 caratteri. L'elenco supporta la ricerca fuzzy tra commit, messaggio, ramo e autore, più filtri su ramo, stato e ambiente, con impaginazione cursore fino a 100 risultati per pagina.
• Deployment checks: registrare un quality gate all'inizio del tuo job CI, poi segnalare il risultato quando finisce. Un controllo required che fallisce sposta il deployment a FAILED e ripristina l'ambiente al precedente deployment riuscito, cioè come rendere la tua suite di test un vero deploy gate.
• Branch protection: regole di pattern glob che bloccano i deployment automatici fino a quando i controlli richiesti non passano e, facoltativamente, qualcuno approva. Fino a dieci regole per progetto.
• Build artifacts: ottenere un URL di download pre-firmato per l'output compilato di un deployment riuscito. L'URL è valido per quindici minuti.
• Project transfer: avviare, annullare e controllare lo stato di un trasferimento a un altro account. Vedi Transferring an Orbit Project.
• Cron jobs: elencare, creare, aggiornare, eliminare, attivare e leggere la cronologia di esecuzione. Vedi Orbit Cron Jobs.
• Timeline annotations: creare e gestire annotazioni incident, release, milestone, note e flag. Vedi Orbit Timeline Annotations.
• Status page: leggere e scrivere la configurazione della pagina di stato pubblica. Vedi Orbit Status Page.
• Edge functions: elencare, creare, aggiornare e distribuire edge handler. Vedi Orbit Edge Functions.

L'autenticazione della sessione dal panel funziona insieme ai token Bearer, quindi un endpoint che puoi chiamare dal tuo browser può generalmente essere chiamato da uno script.

Turbo Remote Cache

La pagina Tokens include anche una scheda Remote Build Cache. Implementa il Turborepo Remote Cache Protocol, permettendo a un monorepo di condividere cache di build tra esecuzioni CI e macchine degli sviluppatori.

Abilitalo sulla scheda, copia il token che genera, e impostalo insieme al tuo account ID come TURBO_TEAM nel tuo ambiente CI. Artefatti fino a 150 MB ciascuno sono accettati. La scheda offre anche Rotate token e Disable.

Se il CI del tuo monorepo passa la maggior parte del tempo a ricostruire pacchetti che non sono cambiati, questo è il singolo elemento di più alto valore su questa pagina.

Gestione dell'Inventario

L'Token inventory elenca ogni token attivo con:

• Quando è stato Created.
• Quando è stato Last used, o Never.
• Quando Expires, con un badge expired una volta scaduto.

La colonna Last used è quella da controllare. Un token che non è mai stato utilizzato è stato configurato male oppure dimenticato, e in entrambi i casi è una credenziale in giro che non fa nulla. L'hint della pagina stessa lo dice chiaramente: revoca tutto ciò che non riconosci.

Revoca di un Token

Fai clic sul controllo di revoca sulla riga. La conferma è esplicita: tutto ciò che si autentica con quel token perde l'accesso immediatamente, e questo non può essere annullato.

Revoca quando una pipeline viene ritirata, quando qualcuno che ha accesso ai tuoi secret CI se ne va, o nel momento in cui sospetti che un token sia trapelato. Non c'è revoca parziale e nessun periodo di grazia, il che è esattamente quello che vuoi nel caso di una fuga.

Risoluzione dei Problemi

401 Unauthorized. L'header è sbagliato oppure il token è stato revocato o è scaduto. Controlla che l'header sia Authorization: Bearer <token> con uno spazio singolo, e che il tuo secret CI non abbia una nuova riga finale.

403 Forbidden. Il token è valido ma manca dello scope per quell'endpoint. Il riferimento elenca lo scope minimo per endpoint. Gli scope sono fissi al momento della creazione, quindi crea un nuovo token con il set corretto.

429 on creation. Hai raggiunto il limite di venti token. Revoca qualcosa dall'inventario.

L'URL dell'artefatto smette di funzionare. Gli URL pre-firmati durano quindici minuti. Richiedi uno nuovo piuttosto che archiviare l'URL.

Un deployment programmato viene rifiutato. L'ora programmata deve essere tra cinque minuti e trenta giorni nel futuro.

Dove Andare Dopo

• Deploying Your Project per vedere cosa fa effettivamente un deployment attivato.
• Orbit Deployment Pipeline per vedere quali gate incontreranno i tuoi deployment API.
• Orbit Plan Limits per vedere cosa include il tuo piano.