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

# API keys and scopes

> Reaching the connector without a browser session.

OAuth clients need no key. Everything else — scripts, CI, self-hosted agents — uses an API
key created under **Settings → API keys** and sent as a bearer token:

```text theme={null}
Authorization: Bearer <your_api_key>
```

## Scopes

A key carries only the scopes you grant it. A route that forgets to declare a scope stays
session-only rather than falling open to every key, so a key never reaches more than it was
given.

| Scope             | Grants                                                      | Tools                                                                                                    |
| ----------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `data:schema`     | Table and column names, types, and your notes. **No data.** | `list_teams`, `list_datasources`, `describe_datasource`, `search_docs`, `list_artifacts`, `get_artifact` |
| `data:read`       | Rows from exposed tables                                    | `run_query`, `run_find`, `run_aggregate`, `sample_rows`                                                  |
| `docs:write`      | Draft documentation for review                              | `document_finding`, `write_documentation`                                                                |
| `docs:publish`    | Publish documentation to every agent on the database        | `publish_documentation`                                                                                  |
| `artifacts:write` | Create, change, and delete dashboards                       | `publish_artifact`, `update_artifact`, `delete_artifact`, `get_artifact_template`                        |

`data:schema` without `data:read` is a genuinely useful combination: an agent can learn the
shape of your database and answer questions about it without ever reading a row.

<Warning>
  `docs:publish` is the widest of these in effect. Published documentation is served to
  every agent querying that database, so a key with it can change how everyone's queries get
  written. Grant it deliberately.
</Warning>

## Handling keys

* Keys are stored hashed. TeamDuo cannot show you one again after it's created.
* Treat a key as equivalent to the access its scopes allow across every exposed datasource
  the owning account can reach.
* Revoke and reissue rather than sharing one between systems — the audit ledger records
  which key ran a query, and that's only useful if a key means one thing.