> For the complete documentation index, see [llms.txt](https://umber.gitbook.io/umber/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://umber.gitbook.io/umber/concepts/api-keys.md).

# API Keys and Authentication

Call the Umber API with a **platform API key**, sent as a bearer token in the `Authorization` header:

```bash
curl "https://api.umbercloud.io/api/v2/{domainId}/va" \
  -H "Authorization: Bearer $UMBER_API_KEY"
```

A platform API key looks like `umber_sk_<keyId>_<secret>`. It covers your whole workspace — every environment — and can do only what its [scopes](#scopes) allow, so a key that only reads assets cannot deploy or delete anything if it leaks. Owners and Admins manage keys on the **Organization** page, under **Platform API Keys**.

## Creating a key

On the **Organization** page, under **Platform API Keys**, choose **Create Platform API Key**, pick its scopes and how long it lasts, and optionally give it a label that says what uses it (for example `CI pipeline`) — worth doing, since the label is how you'll tell keys apart later.

The full key is shown **once**, when you create it. Copy it into your secret store straight away — Umber stores only a hash of the secret and cannot show it again.

## Scopes

A platform key can do only what its scopes allow. A call it isn't scoped for is refused with `403`:

```json
{ "status": 403, "title": "Missing required scope", "detail": "Missing required scope: deploy" }
```

| Scope                              | Allows                                                                                                                                                                                         |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `assets:read`                      | Reading [virtual assets](/umber/api-reference-v2/virtual-assets.md) and their [versions](/umber/api-reference-v2/virtual-assets/versions.md)                                                   |
| `assets:write`                     | Creating and updating virtual assets; uploading versions                                                                                                                                       |
| `assets:delete`                    | Deleting virtual assets and versions                                                                                                                                                           |
| `collections:read`                 | Reading [collections](/umber/api-reference-v2/collections.md) and their deployment status                                                                                                      |
| `collections:write`                | Creating, updating and restoring collections                                                                                                                                                   |
| `collections:delete`               | Deleting and purging collections                                                                                                                                                               |
| `collection-items:read`            | Reading [collection items](/umber/api-reference-v2/collections/collection-items.md)                                                                                                            |
| `collection-items:write`           | Adding, uploading, renaming, moving and copying items, and setting a collection's anchor item                                                                                                  |
| `collection-items:delete`          | Removing items                                                                                                                                                                                 |
| `deploy`                           | Every deploy, undeploy and rollback — [versions](/umber/api-reference-v2/virtual-assets/version-deployment.md) and [collections](/umber/api-reference-v2/collections/collection-deployment.md) |
| `environments:read`                | Reading [environments](/umber/api-reference-v2/environments.md)                                                                                                                                |
| `releases:read` / `releases:write` | Reading and applying releases                                                                                                                                                                  |
| `billing:read`                     | Reading usage and billing information                                                                                                                                                          |

Grant the fewest scopes that work. A read and a write are separate scopes, and so are a write and a delete, so an uploader never needs the power to delete.

## Naming the environment

A platform key covers the whole workspace, so it doesn't imply an environment. Calls that act on **one** environment — deploy, undeploy and rollback — must name it with `envId`, in the path, the query string or the body, as each endpoint describes. Without one, the call is refused:

```json
{ "status": 400, "detail": "envId is required: this key is not tied to one environment, so say which environment to use (in the body, query or path)." }
```

## The Umber CLI

`umber login` creates a platform API key for the [CLI](/umber/cli-tools/umber-cli.md) for you, labelled **umber CLI (computer name)**, with the scopes `assets:read`, `assets:write`, `deploy`, `environments:read` and `billing:read`. It's listed here with your other keys, so you can revoke it the same way. To replace it, run `umber login` again rather than rotating it here — a rotated key is shown only in the dashboard, so the CLI wouldn't receive it. For CI, create a key with those scopes and pass it to `umber login --api-key`.

## AI agents (MCP)

AI agents connect to Umber through its [MCP server](/umber/ai-agents/mcp-server.md), using a platform key like any other caller. The agent can do only what the key's scopes allow, and no MCP tool deletes anything, whatever the scopes. The local server uses the key `umber login` creates. For the hosted server at `https://mcp.umbercloud.io`, create a key for the agent, labelled for who and what uses it (for example `Cursor (Priya)`). Its writes are attributed to you, the person who created it. See [Choosing scopes](/umber/ai-agents/mcp-server.md#choosing-scopes).

## Rotating a key

Choose **Rotate key** (the circular-arrows button) on a key. You get a new key with the same label, scopes and lifetime, shown once. The **old key keeps working for 7 days**, so you can move every system onto the new key without an outage. The **Last Used** column shows whether anything still uses the old one.

## Revoking a key

Choose **Revoke key** (the bin button) and confirm. The key stops working on the very next request. Revoking can't be undone — create a new key if you need one.

## Expiry

Every key has a lifetime, chosen when you create it: 30, 90 or 180 days, or **1 year (the default)**. After that date the key stops working, and requests with it get `403`. You can also choose **Never**, but an expiring key is safer — a forgotten or leaked key stops working on its own.

The **Expires** column shows each key's date, and a key within 30 days of it is marked **Expires soon**. Rotate it before then: the new key gets the same lifetime as the old one, and the old key keeps working for 7 days while you switch over.

## Secured downloads use download keys

Platform API keys are for the API. Fetching a **secured** asset from the delivery network (`adn.umbercloud.io`) uses a different credential, the environment's **download key**, sent in the `apikey` header. Download keys belong to one environment and are managed on that environment's page in the dashboard. Use each key for its own job: platform API keys to call the API, download keys to fetch secured content.

## Errors

| Status | Meaning                                                                                                                                             |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | A deploy, undeploy or rollback made with a platform key didn't name `envId`.                                                                        |
| `403`  | No `Authorization: Bearer` key, or the key is unknown, revoked or expired — or it's valid but lacks the scope the call needs (the body says which). |