Authentication

Onepin uses API keys for all REST API, SDK, and CLI access. The MCP server is the exception — it signs you in with OAuth and takes no key.

Create a key

Go to 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:

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

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.