> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dbhost.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

> Generate and manage API keys for programmatic access.

## Creating an API key

1. Go to **Settings** in the sidebar
2. Click **Create Key**
3. Enter a label (e.g., "CI/CD pipeline", "Monitoring script")
4. Choose a scope
5. Copy the key immediately

<Note>
  API key creation requires a Pro or Business plan. Free users will see an upgrade prompt instead of the create form.
</Note>

<Warning>
  Each full API key secret is shown only once when created or replaced. DBHost stores only a hash plus the visible prefix, so the current secret cannot be recovered later. Save it in a secure location.
</Warning>

## Key scopes

* `Selected databases (Recommended)` limits the key to only the databases you choose. It can list and manage only those databases.
* `Full account access` can create and manage every database in your account.

Selected-database keys cannot create new databases. If your automation needs to provision databases, create a full-access key instead.

Selected-database keys also follow least-privilege behavior in the API and CLI:

* `GET /api/v1/databases` returns only the selected databases
* Database-specific routes outside scope return `DATABASE_NOT_FOUND`
* Full-account-only routes like database creation return `KEY_SCOPE_DENIED`

API key scope is immutable in v1. To change scope, revoke the key and create a new one.

## Replacing a key

Click **Replace key** next to an existing key if you need a fresh secret without changing the label or scope bindings.

* The old secret stops working immediately
* The new secret is shown once right after replacement
* The key keeps the same label and scope configuration

### Safe rotation checklist

**Replace key** is an immediate cutover. Use it only when every consumer can be
updated at the same time. If you need a zero-downtime rotation, create a second
key with the same least-privilege scope, migrate the consumers, verify the new
key, and then revoke the old key.

1. Inventory every script, environment variable, CI job, and secret store that
   uses the current key.
2. Prepare the destination for the new secret before creating or replacing the
   key.
3. Copy the new secret immediately and update every consumer.
4. Run a read-only command such as `dbhost databases list` from the real
   consumer environment.
5. Revoke the old key if you used an overlapping second key, then remove the old
   secret from temporary notes and local shells.

If the required scope or selected-database bindings have changed, create a new
key instead of using **Replace key**.

## Using API keys

Include the key in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer dbh_abc123..." \
  https://dbhost.app/api/v1/databases
```

Or use it with the [CLI](/cli):

```bash theme={null}
dbhost auth login --api-key dbh_abc123...
```

## Key format

API keys have a visible **prefix** (e.g., `dbh_abc1`) for identification and a secret portion. In the settings page, you'll see the prefix, label, scope, and last-used timestamp.

## Revoking a key

Click **Revoke** next to any key in the settings page. The key stops working immediately.