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

Creating a key

1. Sign in at app.onepin.ai.
2. Go to Settings → API Keys.
3. 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:

If no key is found from any source, the SDK raises OnePinConfigurationError and 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.

Scopes

Select the minimum set of scopes your key needs.

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:

1. Create a replacement key in the dashboard with the same scopes.
2. Update ONEPIN_API_KEY in your CI secrets or secrets manager.
3. Verify the new key with onepin whoami.
4. 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.