Orbit API Tokens and the REST API

API tokens let a script, a CI pipeline or your own tooling drive Orbit without a browser session: trigger deployments, report CI check results, download build artifacts, manage cron jobs and more, all authenticated with a Bearer token you scope yourself.

Where Tokens Live

Open Orbit and choose Tokens from the top-level navigation. The page is titled API Access Tokens and states its own rule up front: tokens are shown once at creation.

The full endpoint documentation sits one click away. The API Reference card has a View docs button that opens the in-panel reference for every Orbit endpoint.

Creating a Token

1. Click New token.
2. Give it a Token name. Name it after the thing that will use it, for example the CI workflow, so the inventory is readable later.
3. Choose its Scopes.
4. Optionally set an Expiry. Leave it blank for a token that does not expire.
5. Click Create token.

The raw token is displayed once, under a One-time reveal heading, with a copy button. Paste it straight into your CI secret store. There is no way to see it again: only a SHA-256 hash of the token is stored, so even Kapsule cannot recover it for you.

An account can hold up to 20 active tokens. Creating a twenty-first is refused with a message telling you to revoke an existing one first.

Scopes

Scopes are the whole point of tokens: each one carries only the permissions you gave it.

A new token defaults to deploy:write and project:read, which is what a deployment pipeline needs and nothing more.

Grant the smallest set that does the job. A token that only needs to report a CI result does not need project:write. A read-only monitoring script needs neither write scope. Each endpoint in the reference lists the minimum scope it requires.

Using a Token

Authentication is a Bearer header against the API base, 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"}'

The Tokens page carries a ready-made CI/CD usage snippet and a GitHub Actions starter workflow. The starter is saved as .github/workflows/orbit-deploy.yml and needs two repository secrets, ORBIT_TOKEN and ORBIT_PROJECT_ID. Copy both from the page rather than transcribing them.

What the API Covers

The in-panel reference documents each area with its parameters and required scope:

• Deployments: trigger a deploy, optionally on a named branch, optionally scheduled for a future time between five minutes and thirty days ahead, with a note of up to 500 characters. Listing supports fuzzy search across commit, message, branch and author, plus filters on branch, status and environment, with cursor pagination up to 100 results per page.
• Deployment checks: register a quality gate at the start of your CI job, then report the result when it finishes. A required check that fails moves the deployment to FAILED and reverts the environment to the previous successful deployment, which is how you make your own test suite a genuine deploy gate.
• Branch protection: glob-pattern rules that block automatic deploys until required checks pass and, optionally, someone approves. Up to ten rules per project.
• Build artifacts: get a pre-signed download URL for a succeeded deployment's compiled output. The URL is valid for fifteen minutes.
• Project transfer: initiate, cancel and check the status of a transfer to another account. See Transferring an Orbit Project.
• Cron jobs: list, create, update, delete, trigger, and read execution history. See Orbit Cron Jobs.
• Timeline annotations: create and manage incident, release, milestone, note and flag annotations. See Orbit Timeline Annotations.
• Status page: read and write the public status page configuration. See Orbit Status Page.
• Edge functions: list, create, update and deploy edge handlers. See Orbit Edge Functions.

Session authentication from the panel works alongside Bearer tokens, so an endpoint you can call from your browser can generally be called from a script too.

Turbo Remote Cache

The Tokens page also carries a Remote Build Cache card. It implements the Turborepo Remote Cache Protocol, letting a monorepo share build caches between CI runs and developer machines.

Enable it on the card, copy the token it generates, and set it alongside your account ID as TURBO_TEAM in your CI environment. Artifacts up to 150 MB each are accepted. The card also offers Rotate token and Disable.

If your monorepo's CI spends most of its time rebuilding packages that have not changed, this is the single highest-value thing on the page.

Managing the Inventory

The Token inventory lists every active token with:

• When it was Created.
• When it was Last used, or Never.
• When it Expires, with an expired badge once it has.

The Last used column is the one to audit. A token that has never been used is either misconfigured or forgotten, and either way it is a credential sitting around doing nothing. The page's own hint says it plainly: revoke anything you do not recognise.

Revoking a Token

Click the revoke control on the row. The confirmation is explicit: everything authenticating with that token loses access immediately, and this cannot be undone.

Revoke when a pipeline is retired, when someone with access to your CI secrets leaves, or the moment you suspect a token has leaked. There is no partial revocation and no grace period, which is exactly what you want in the leak case.

Troubleshooting

401 Unauthorized. The header is wrong or the token has been revoked or expired. Check the header is Authorization: Bearer <token> with a single space, and that your CI secret does not have a trailing newline.

403 Forbidden. The token is valid but lacks the scope for that endpoint. The reference lists the minimum scope per endpoint. Scopes are fixed at creation, so create a new token with the right set.

429 on creation. You are at the twenty-token limit. Revoke something from the inventory.

The artifact URL stops working. Pre-signed URLs last fifteen minutes. Request a fresh one rather than storing the URL.

A scheduled deployment is rejected. The scheduled time must be between five minutes and thirty days in the future.

Where To Go Next

• Deploying Your Project for what a triggered deployment actually does.
• Orbit Deployment Pipeline to see which gates your API deploys will meet.
• Orbit Plan Limits for what your plan includes.