# API Keys and Developer Access

Source: https://support.kapsulehost.com/en-us/developer-api-access

KapsuleHost 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.

![API Keys card in KPanel security settings with the scope chips visible](https://support.kapsulehost.com/help/screenshots/developer-api-access.8d15f634.webp)

1. Go to **Settings**, then **Security**.
2. Scroll to **API Keys** and click **New key**.
3. 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.
4. Click the scope chips to select what the key may do. Three read scopes are preselected: `read:sites`, `read:email`, and `read:domains`. Click a chip to add or remove it.
5. 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.

> **Warning:** 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 |

> **Note:** 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.

```sh
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.

> **Tip:** 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.

> **Important:** 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](https://support.kapsulehost.com/en-us/account-team-members) 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](https://support.kapsulehost.com/en-us/account-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."

1. Go to **Settings**, then **Developer**.
2. Click **Enable remote cache**.
3. 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`:

```sh
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
```

The team ID is your KapsuleHost 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 KapsuleHost 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.

## 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](https://support.kapsulehost.com/en-us/account-security) and check [the audit log](https://support.kapsulehost.com/en-us/account-audit-log) for what else changed.