> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://onepin.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://onepin.ai/docs/_mcp/server.

# Authentication

Onepin uses API keys for all REST API, SDK, and CLI access. The [MCP server](/docs/get-started/mcp-server) is the exception — it signs you in with OAuth and takes no key.

## Create a key

Go to [app.onepin.ai](https://app.onepin.ai) → **Settings → API → Create new key**, select the scopes you need, and copy the value — it's shown only once.

A key is scoped to a single workspace: every resource it touches — workflows, templates, uploads — lives in the workspace it was created under.

## Use the key

Run `onepin login` once and paste the key:

```bash
onepin login
```

It's stored and picked up automatically by both the CLI and the SDK — `OnepinClient()` needs no arguments.

To pass the key explicitly instead (CI, or without `onepin login`):

* **SDK:** `OnepinClient(api_key="op_live_...")`
* **CLI:** `--api-key op_live_...`
* **Env:** `export ONEPIN_API_KEY=op_live_...`

Resolution order: explicit `api_key` → `ONEPIN_API_KEY` → the key saved by `onepin login`.

## Scopes

Pick the minimum your key needs:

| Scope              | Grants                                            |
| ------------------ | ------------------------------------------------- |
| `templates:read`   | List and get templates                            |
| `workflows:read`   | List and get workflows                            |
| `workflows:run`    | Start and cancel runs                             |
| `workflows:write`  | Create, update, delete workflows; clone templates |
| `voices:read`      | List voices                                       |
| `voices:write`     | Manage voice favorites                            |
| `uploads:write`    | Create and confirm uploads                        |
| `dictionary:read`  | List and search dictionary entries                |
| `dictionary:write` | Create and update dictionary entries              |
| `catalog:read`     | Read the provider/model catalog                   |
| `workspace:read`   | Read workspace metadata and usage                 |

## Keep keys safe

> **Warning**
>
> A key grants full API access for its scopes — treat it like a password. Keep it out of source control; store it in a secrets manager or a local `.env` file. Rotate or revoke a key anytime in **Settings → API**.