Skip to main content
All Planasonix REST endpoints require authentication. You use API keys tied to your workspace; username/password flows apply to the browser only and are not supported for automation.

​
API key creation

Create keys in API keys under organization settings.
1

Choose principal

Decide whether the key acts as you (inherits your RBAC) or as a service principal with explicit scopes.
2

Set scopes

Enable only what the integration needs: read pipelines, trigger runs, manage connections, or admin operations.
3

Store securely

Copy the secret once into a vault; treat rotation as a normal operational task.

​
Header format

Send the key in the Authorization header using the Bearer scheme: 
Authorization: Bearer YOUR_API_KEY_HERE
Some legacy integrations accept: 
X-Planasonix-Api-Key: YOUR_API_KEY_HERE
Prefer Bearer for new code; your workspace documentation marks deprecated headers if both exist during a transition.

​
Scopes

Scopes limit blast radius when a key leaks. Examples (names illustrative—match your OpenAPI security definitions):
ScopeAllows
pipelines:readList and fetch pipeline definitions and metadata
pipelines:runStart and cancel runs
connections:readView connection metadata (not secret values)
connections:writeCreate and rotate connections
admin:organizationManage users, SSO, billing interfaces
CI jobs that only trigger runs should use pipelines:run plus pipelines:read—not full admin scopes.

​
User keys vs service keys

Bound to your account; permissions match your team memberships until an admin removes you. Good for personal scripts; avoid for production automation tied to a person.

​
Failed authentication

StatusMeaning
401 UnauthorizedMissing header, malformed token, or revoked key
403 ForbiddenValid key but insufficient scope or resource policy
Error bodies include a machine-readable code and human-readable message. Do not log full keys in application logs when debugging 401s.

​
IP and session policies

If your workspace enables Session policy IP allowlists, API calls from disallowed networks fail with 403 even when the key is valid. Add automation egress ranges explicitly.

API reference

Base URL, rate limits, and JSON envelopes.

Teams and permissions

How human roles relate to API access for user-bound keys.