Authentication

OnePin uses API keys for all programmatic access (SDK and CLI). Browser-based access uses Clerk session tokens, which are not covered here.

API key format

Keys are 32-character base62 strings prefixed op_live_:

op_live_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6

v0.2: Test-environment keys (op_test_*) are not yet available.

Creating a key

Sign in at app.onepin.ai.
Go to Settings → API Keys.
Click Create key, enter a name, select the scopes you need, and copy the value.

The plaintext value is shown exactly once. Store it in a secrets manager or environment variable immediately.

Credential resolution order

The CLI and SDK resolve credentials from three sources, in priority order:

Priority	Source	How
1 (highest)	`--api-key TEXT` flag	CLI flag or `token=` constructor argument
2	`ONEPIN_API_KEY` environment variable	`export ONEPIN_API_KEY=op_live_...`
3 (lowest)	`~/.onepin/credentials` file	Written by `onepin login`

The CLI reads ONEPIN_API_KEY and the credentials file automatically. The SDK does not — pass the token explicitly: OnePinClient(token=os.environ["ONEPIN_API_KEY"]). If no key is found, the CLI exits with an error.

Credentials file

onepin login writes a TOML credentials file at ~/.onepin/credentials:

1 [default]
2 api_key = "op_live_..."
3 base_url = "https://api.onepin.ai"

File permissions are enforced on write: 0600 on the file, 0700 on the ~/.onepin/ directory. The SDK and CLI refuse to load credentials from a world-readable file.

v0.2: Named profiles (--profile staging) are not yet implemented. The [default] profile is the only one used in v0.1.

Scopes

Select the minimum set of scopes your key needs.

Scope	Description
`templates:read`	List and get workflow templates from the gallery
`workflows:read`	List and get workflows in your workspace
`workflows:run`	Start and cancel workflow runs
`workflows:write`	Create, update, and delete workflows; clone templates into workflows
`voices:read`	List voices available to your workspace
`voices:write`	Manage voice favorites
`uploads:write`	Create upload sessions and confirm uploads
`dictionary:read`	List and search custom pronunciation dictionary entries
`dictionary:write`	Create and update dictionary entries
`workspace:read`	Read workspace metadata

Cloning a template into a workflow requires workflows:write — the clone creates a new workflow in your workspace.

Key rotation

Rotate keys every 90 days or immediately after any suspected exposure:

Create a replacement key in the dashboard with the same scopes.
Update ONEPIN_API_KEY in your CI secrets or secrets manager.
Verify the new key with onepin whoami.
Revoke the old key in the dashboard.

Never commit keys to source control. Add ONEPIN_API_KEY to .gitignore and use .env files only for local development.

Workspace binding

Each key is bound to a single workspace at creation time. All resources created via that key — workflows, uploads — belong to that workspace. To operate on a different workspace, create a key under that workspace.

The X-Workspace-Id header is optional on API calls made with an API key; the server derives the workspace from the key. If you supply the header, the value must match the key’s bound workspace or the request is rejected with 403.