# Manage DSN keys

Add a DSN key to a project, give it its own rate limit, and revoke a key so the ingest refuses it within seconds.

A DSN key only lets its holder send events, never read them, so it is safe in a browser bundle.
Give each app or environment its own key when you want to revoke one without the others. Replace
_project-id_ with the project's id and _key-id_ with the key's id.

## Prerequisites

- Permission for `errors:UpdateProject` on the project. Without it, the **Setup** tab says "Adding
  or revoking keys needs errors:UpdateProject."
- In the console, also `errors:ListProjects` on the project to open it (without it the project is
  not found).

## Add a key

A project has at most 20 active keys.

**Console**
1. Open the project, then the **Setup** tab.
2. Under **DSN keys**, choose **Add key**.

The new key appears in the table, labelled **Key** and a number, with the project's rate limit.
To give it a label or a rate limit of its own, use the CLI or the API.

**CLI**
```sh
dcloud errors keys create project-id --label staging --rate-limit-per-minute 1000
```

**API**
```http
POST /errors/api/projects/project-id/keys
{ "label": "staging", "rateLimitPerMinute": 1000 }
```

The answer is `201` with the key and its `dsn`. Without `rateLimitPerMinute` the key has none of
its own, and only the project's and the organization's limits apply.

`409` "A project has at most 20 active keys" when the project has 20 already.

## Revoke a key

**Warning:**
SDKs still sending with a revoked key are refused with the message "unknown or revoked DSN key"
(status `401`) and drop their events without retrying. Events already received stay.

The key labelled **Managed (connected apps and CI)** is the one connected apps and CI environments
use. To replace it, rotate it instead (see [Rotate the managed key](rotate-the-managed-key.md)).

**Console**
1. Open the project, then the **Setup** tab.
2. Under **DSN keys**, open the key's action menu and choose **Revoke key**.
3. Choose **Revoke**.

**CLI**
```sh
dcloud errors keys revoke project-id key-id
```

**API**
```http
DELETE /errors/api/projects/project-id/keys/key-id
```

The answer is `200` with the key's id and `status` `revoked`; `404` when the key does not exist or
is revoked already.

## Result

The ingest refuses a revoked key within seconds. A revoked key stays listed with its status, and
the DSN in the project's header is the first active key's; with none left it reads "No active key".

## Related

- [Change project settings](change-project-settings.md): the project's rate limit.
- `errors.keys.create` · `dcloud errors keys revoke`
