Kapsule Orbit API-tokens en de REST API

API-tokens stellen scripts, CI-pijplijnen en uw eigen tooling in staat om Kapsule Orbit zonder browsersessie aan te sturen: implementaties activeren, CI-controleresultaten rapporteren, build-artefacten downloaden, cronjobs beheren en meer, allemaal geverifieerd met een Bearer-token die u zelf instelt.

Waar tokens zich bevinden

Open Kapsule Orbit en kies Tokens in de navigatie op het hoogste niveau. De pagina heet API Access Tokens en stelt meteen de regel duidelijk: tokens worden slechts eenmaal weergegeven bij aanmaak.

De volledige documentatie van het eindpunt is slechts één klik verwijderd. De API Reference-kaart bevat een View docs-knop die de ingebouwde referentie voor elk Kapsule Orbit-eindpunt opent.

Een token aanmaken

1. Klik op New token.
2. Geef het een Token name. Noem het naar het item dat het zal gebruiken, bijvoorbeeld de CI-workflow, zodat de inventaris later leesbaar is.
3. Kies de Scopes.
4. Stel desgewenst een Expiry in. Laat het leeg voor een token die niet vervalt.
5. Klik op Create token.

Het ruwe token wordt eenmaal weergegeven, onder een One-time reveal-kopje, met een knop om te kopiëren. Plak het rechtstreeks in uw CI-secretopslag. Er is geen manier om het opnieuw te zien: alleen een SHA-256-hash van het token wordt opgeslagen, dus zelfs KapsuleHost kan het niet voor u herstellen.

Een account kan maximaal 20 actieve tokens bevatten. Het aanmaken van een eenentwintigste wordt geweigerd met een bericht dat u aangeeft om eerst een bestaande in te trekken.

Scopes

Scopes zijn het hele punt van tokens: elk draagt alleen de machtigingen die u het hebt gegeven.

Een nieuw token heeft standaard deploy:write en project:read, wat een implementatiepijplijn nodig heeft en niets meer.

Verleen de kleinste set die het werk doet. Een token die alleen een CI-resultaat moet rapporteren, hoeft project:write niet. Een alleen-lezen monitoringscript heeft geen enkele schrijfscope nodig. Elk eindpunt in de referentie geeft de minimale scope aan die het vereist.

Een token gebruiken

Verificatie is een Bearer-header tegen de API-basis, 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"}'

De Tokens-pagina bevat een kant-en-klaar CI/CD usage-fragment en een GitHub Actions starter-workflow. De starter wordt opgeslagen als .github/workflows/orbit-deploy.yml en vereist twee repository-secrets, ORBIT_TOKEN en ORBIT_PROJECT_ID. Kopieer beide van de pagina in plaats van ze over te typen.

Wat de API afdekt

De ingebouwde referentie documenteert elk gebied met zijn parameters en vereiste scope:

• Deployments: een implementatie activeren, optioneel op een benoemde branch, optioneel gepland voor een toekomstig moment tussen vijf minuten en dertig dagen vooruit, met een opmerking van maximaal 500 tekens. De aanbieding ondersteunt fuzzy-zoekopdrachten in commit, bericht, branch en auteur, plus filters op branch, status en omgeving, met cursorpaginering tot 100 resultaten per pagina.
• Deployment checks: registreer een quality gate aan het begin van uw CI-job en rapporteer het resultaat wanneer deze klaar is. Een required controle die mislukt, verplaatst de implementatie naar FAILED en zet de omgeving terug naar de vorige succesvolle implementatie. Dit is hoe u uw eigen testsuite een echte implementatiepoort maakt.
• Branch protection: glob-patternregels die automatische implementaties blokkeren totdat vereiste controles slagen en, optioneel, iemand goedkeurt. Tot tien regels per project.
• Build artifacts: krijg een vooraf ondertekende download-URL voor de gecompileerde uitvoer van een geslaagde implementatie. De URL is vijftien minuten geldig.
• Project transfer: initieer, annuleer en controleer de status van een overdracht naar een ander account. Zie Transferring an Orbit Project.
• Cron jobs: lijst, maak, update, verwijder, activeer en lees uitvoeringsgeschiedenis. Zie Orbit Cron Jobs.
• Timeline annotations: maak en beheer incident-, release-, milestone-, note- en flag-aantekeningen. Zie Orbit Timeline Annotations.
• Status page: lees en schrijf de openbare statuspagina-configuratie. Zie Orbit Status Page.
• Edge functions: lijst, maak, update en implementeer edge-handlers. Zie Orbit Edge Functions.

Sessieverstifying van het paneel werkt naast Bearer-tokens, dus een eindpunt dat u vanuit uw browser kunt aanroepen, kan meestal ook vanuit een script worden aangeroepen.

Turbo Remote Cache

De Tokens-pagina bevat ook een Remote Build Cache-kaart. Dit implementeert het Turborepo Remote Cache Protocol en stelt een monorepo in staat buildcaches tussen CI-uitvoeringen en ontwikkelaarsmachines te delen.

Schakel het in op de kaart, kopieer het gegenereerde token en stel het in samen met uw account-ID als TURBO_TEAM in uw CI-omgeving. Artefacten tot 150 MB elk worden geaccepteerd. De kaart biedt ook Rotate token en Disable.

Als de CI van uw monorepo het meeste van zijn tijd besteedt aan het opnieuw opbouwen van pakketten die niet zijn gewijzigd, is dit het enige item met de hoogste waarde op de pagina.

De inventaris beheren

De Token inventory geeft elk actief token weer met:

• Wanneer het is Created.
• Wanneer het is Last used, of Never.
• Wanneer het Expires, met een expired-badge zodra dat het geval is.

De kolom Last used is degene die u moet controleren. Een token dat nooit is gebruikt, is óf verkeerd geconfigureerd óf vergeten, en in beide gevallen is het een credential die niets doet. De hint van de pagina zelf zegt het duidelijk: trek alles in wat u niet herkent.

Een token intrekken

Klik op het intrekningsbesturingselement in de rij. De bevestiging is expliciet: alles dat zich verificaert met dat token, verliest onmiddellijk de toegang, en dit kan niet ongedaan worden gemaakt.

Trek in wanneer een pijplijn wordt stilgelegd, wanneer iemand met toegang tot uw CI-secrets vertrekt, of op het moment dat u vermoedt dat een token is gelekt. Er is geen gedeeltelijke intrekking en geen respijtperiode, wat precies is wat u wilt in het lekgeval.

Probleemoplossing

401 Unauthorized. De header is onjuist of het token is ingetrokken of verlopen. Controleer of de header Authorization: Bearer <token> met een enkele spatie is, en dat uw CI-secret geen spatie aan het einde heeft.

403 Forbidden. Het token is geldig maar mist de scope voor dat eindpunt. De referentie geeft de minimale scope per eindpunt aan. Scopes worden vastgesteld bij aanmaak, dus maak een nieuw token met de juiste set.

429 on creation. U bent op de twintig-tokengrens. Trek iets uit de inventaris in.

The artifact URL stops working. Vooraf ondertekende URL's houden vijftien minuten mee. Vraag om een vers exemplaar in plaats van de URL op te slaan.

A scheduled deployment is rejected. Het geplande moment moet tussen vijf minuten en dertig dagen in de toekomst liggen.

Waar u vervolgens heen gaat

• Deploying Your Project voor wat een geactiveerde implementatie werkelijk doet.
• Orbit Deployment Pipeline om te zien welke poorten uw API-implementaties zullen passeren.
• Orbit Plan Limits voor wat uw plan omvat.