Documentation
Tokens and API keys
Database tokens for DuckDB clients, and organization API keys for the REST API and MCP.
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 and MCP |
| 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.
API keys
API keys are created by organization owners and admins under 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:
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.