Every request to the Sublayr API — whether from the CLI, SDK, or a direct HTTP call — is authenticated with an API key. This guide covers generating, using, scoping, and rotating keys safely.
Generating a key
From your dashboard, go to Settings > API Keys and click Create Key. Give it a descriptive name (e.g. "production-backend" or "ci-pipeline") so you can identify its usage later. Sublayr shows the full key value only once at creation — store it securely, such as in a secrets manager or environment variable.
Using a key
Pass your key as a bearer token on every API request:
If you're using the SDK, set it as an environment variable and the client picks it up automatically:
Key scopes
Keys can be scoped to limit what they're allowed to do:
Scope | Description |
|---|---|
| View agent configs and status |
| Create, update, and deploy agents |
| View run traces and history |
| Modify budgets and spend limits |
Scope keys to the minimum access a given integration needs — for example, a monitoring dashboard should use a read-only key, never a key with write access.
Rotating and revoking keys
Rotate a key at any time by generating a new one and updating it wherever it's used, then revoking the old key from the dashboard. Revocation takes effect immediately — any request using a revoked key returns a 401 within seconds.
Team and workspace keys
On Growth and Enterprise plans, keys can be created per-workspace or per-team, so different teams' agents are isolated from each other even within the same organization. Enterprise plans additionally support SSO/SAML for dashboard access, separate from API key authentication.
Security recommendations
Never commit API keys to source control
Use separate keys for development, staging, and production
Rotate keys on a regular schedule, and immediately if one is ever exposed
Prefer scoped keys over full-access keys wherever possible
