Account
API Keys and Developer Access
Kapsule gives you two developer surfaces: scoped API keys for reading your account programmatically, and a remote build cache that speeds up Turborepo and Nx builds on your own machines and CI runners.
Neither is enabled by default. Both are created from Settings, and both hand you a secret exactly once.
Creating an API Key
API keys live under Settings, then Security, in the API Keys card.
- Go to Settings, then Security.
- Scroll to API Keys and click New key.
- Give the key a name. The field suggests "Key name (e.g. My automation script)". The name is only for you, so make it say where the key will be used.
- Click the scope chips to select what the key may do. Three read scopes are preselected:
read:sites,read:email, andread:domains. Click a chip to add or remove it. - Click Create.
The full key appears once, in a green panel headed "Copy now". Copy it straight into your secret store. When you dismiss that panel the key is gone: only a short prefix is kept, which is all the list can ever show you again.
The key is never displayed a second time and cannot be recovered. If you lose it, revoke that key and create a new one. Do not paste it into a shared document, a ticket, a commit, or a chat message.
Only the Owner and Admin roles can create a key. Any other role gets a permissions error. When a key is created, a security alert email goes to the address of whoever created it, so an unexpected one of those is worth investigating immediately.
The Scopes
Seven scopes are offered:
| Scope | Grants |
|---|---|
read:sites | Reading your websites |
write:sites | Reserved for write operations on websites |
read:email | Reading your mailboxes |
write:email | Reserved for write operations on mailboxes |
read:domains | Reading your domains |
write:domains | Reserved for write operations on domains |
read:billing | Reserved for reading billing data |
The customer API is read-only today. The write: scopes and read:billing can be selected on a key, but no customer endpoint currently consumes them, so granting them changes nothing. Grant only the read scopes you actually need and revisit the key when write endpoints ship.
Using a Key
Send the key as a bearer token on the Authorization header.
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
Three endpoints accept a customer API key:
| Endpoint | Scope required | Returns |
|---|---|---|
GET /api/v1/sites | read:sites | Your websites, with domain, application type and status |
GET /api/v1/domains | read:domains | Your domains, with status and expiry |
GET /api/v1/mailboxes | read:email | Your mailboxes |
A request with no key, an unknown key, or a revoked key returns 401. A valid key without the right scope returns 403 with a message naming the scope that was needed. Every successful call updates the key's last-used timestamp.
Poll gently. These endpoints read live account data, and a tight loop against them is indistinguishable from abuse. Once a minute is generous for anything a dashboard needs; once an hour is usually plenty.
Reviewing and Revoking Keys
The API Keys table lists each active key by Name, Prefix (the visible beginning of the key), and Scopes. Click Revoke at the end of a row to kill it.
Revoking takes effect immediately and there is no confirmation dialog. The next request using that key fails with 401. A revoked key cannot be restored, so make sure you know what is using it before you click.
Keys belong to the account, not to the person who created them. Removing a teammate from the Team page does not revoke keys they made. Build a key review into your offboarding: remove the person, then come here and revoke anything they created.
Key creation and revocation are both recorded in the audit log under the api_key.* actions, with the actor and the originating IP address.
The Remote Build Cache
The Developer page, in the Advanced group of the settings rail, offers a Remote Build Cache. The panel describes it as a way to "Accelerate Turborepo and Nx builds by sharing a distributed cache across machines and CI pipelines."
- Go to Settings, then Developer.
- Click Enable remote cache.
- Copy the token from the panel headed "New token generated. Copy it now, it won't be shown again".
Then set two environment variables in your CI configuration or local .env.local:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
The team ID is your Kapsule account ID, shown in the setup instructions on the same page.
The page states its own compatibility: Turborepo 1.x and later, Nx 16 and later, and any tool implementing the same remote cache protocol. Artifacts are stored per account and are never shared across accounts.
Two further controls sit on the card:
- Rotate token issues a new token and invalidates the old one. Any CI job still holding the old token stops using the cache, so rotate and update your secrets together.
- Disable turns the cache off entirely.
Choosing Between the Two
They solve unrelated problems and are not interchangeable.
Use an API key when something outside Kapsule needs to know the state of your account: a status board that lists your sites, a script that warns you about domains expiring soon, an inventory export.
Use the remote build cache when your builds are slow because every machine and every CI run rebuilds the same unchanged packages. It has nothing to do with your hosted sites and does not read your account data.
If you are deploying from Git rather than calling an API, look at Orbit instead. It builds and ships from your repository directly, with build caching handled for you.
Troubleshooting
Every request returns 401. Confirm you sent the header as Authorization: Bearer <key> with a single space, that the key was not truncated when you copied it, and that it has not been revoked. Compare the beginning of your key with the Prefix column to make sure you are using the key you think you are.
A request returns 403 naming a scope. The key does not carry that scope. Scopes are fixed when the key is created, so create a replacement with the right scopes and revoke the old one.
I cannot see the API Keys card. It is on the Security page, not the Developer page. The Developer page holds only the build cache.
The New key button does nothing. Your role is below Admin. Ask the Owner or an Admin.
Builds are not hitting the cache. Check that both TURBO_TOKEN and TURBO_TEAM are present in the build environment, that the token has not been rotated since you set it, and that the page still shows the Active badge.
A key I did not create appeared. Treat it as a compromise. Revoke it, then work through Account Security and check the audit log for what else changed.