# Tokens and API keys

> Database tokens for DuckDB clients, and organization API keys for the REST API and MCP.

Source: https://duckhouse.co/docs/tokens

There are two kinds of credential, and they open different doors.

|  | Database token | API key |
| --- | --- | --- |
| Looks like | `dh_…` | `dhk_…` |
| Belongs to | One database | Your organization |
| Used by | DuckDB clients, over Quack | The [REST API](https://duckhouse.co/docs/api.md) and [MCP](https://duckhouse.co/docs/mcp.md) |
| Can | Read and write everything in that database | Manage databases and run queries, within its scope |
| Create it | On the database’s page | Settings → Organization → API keys |

## Database tokens

A database gets one token when it is created, and you can add as many more as you like from its page. Give each person, application or notebook its own, named for what it is, so that you can revoke one without disturbing the rest.

-   Copy a token when it is created, and keep it somewhere safe, such as a password manager.
-   A token can be given an expiry date.
-   Adding or revoking a token restarts the database so that it picks up the change. It is unreachable for a few seconds.

> Every token has full access
>
> DuckDB's protocol has no notion of a read-only user yet, so any token can read, write and drop anything in its database. When you need read-only access, for a dashboard or an AI agent, use a **read-scoped API key** instead: the REST API and MCP enforce it.

## API keys

API keys are created by organization owners and admins under [Settings → Organization](https://duckhouse.co/dashboard/settings/organization). A key is shown once, when it is created: we keep only a hash of it, so it cannot be displayed again. If you lose one, revoke it and create another.

| Scope | Allows |
| --- | --- |
| `read` | List and inspect databases, read their schemas, and run read-only queries. |
| `full` | Everything above, plus creating and deleting databases, managing Connections, and running queries that write. |

Send the key as a bearer token:

```bash
curl https://duckhouse.co/api/v1/databases \
  -H "Authorization: Bearer $DUCKHOUSE_API_KEY"
```

-   An API key cannot create other API keys. That always takes a signed-in person.
-   Revoking a key takes effect immediately.
-   How read-only is enforced: the SQL is parsed before it is sent, and anything other than a plain query is refused. That includes writes, `COPY`, `ATTACH`, settings changes, and a second statement hidden after a semicolon.

## If a credential leaks

Revoke it, then create a replacement. For a database token that means a restart of a few seconds; for an API key there is no interruption. Nothing else needs rotating: each credential is independent.