API keys
API keys authenticate SDK requests. A key can be organization-wide or scoped to selected workspaces, and its capabilities determine which endpoints it can use.
Create
- Settings -> API Keys -> New Key in the dashboard.
- Name it. Set an optional expiry.
- Pick a scope (below).
- Copy the raw key immediately — it's shown once and stored as a hash.
The dashboard keeps a key_prefix (first 12 chars) so you can identify a key later without revealing the secret.
Scopes
| Scope | What it can do | Use when |
|---|---|---|
full_org | Ingest into any workspace in the org. | Single-team orgs. |
workspace_scoped | Ingest only into the workspaces you list. | Per-env or per-team keys. |
Use workspace_scoped for an environment that should write only to selected workspaces. Verify the configured scope in the dashboard before deployment.
Capabilities
Tracing requires traces:write. Guard evaluation requires guard:evaluate when Guard is configured. Grant only the capabilities the process uses.
A workspace-scoped key must send an explicit workspace_slug included in its allowed workspace set. Disabled organizations or workspaces, revoked keys, and expired keys are rejected immediately.
During onboarding, use a key scoped to the selected workspace and set STASO_WORKSPACE_SLUG explicitly. If the raw secret is lost, create or rotate to replacement material in the dashboard, update STASO_API_KEY, restart long-lived processes, verify delivery, and revoke any old key that should no longer be used.
Use the key
st.init(api_key="ak_live_...", workspace_slug="prod")export STASO_API_KEY=ak_live_...
export STASO_WORKSPACE_SLUG=prodLong-lived SDK processes read their credential at startup. Restart them after replacing a key.
Rotate
- Rotate the key in the dashboard.
- Copy the replacement material when it is returned; it is shown once.
- Replace the local environment variable or hook credential entry.
- Restart long-lived SDK processes and confirm requests with the replacement.
Server-side rotation revokes the prior key atomically. The Python SDK does not rotate or revoke keys itself. If you need a staged overlap, create a separate key, deploy it, verify it, and then revoke the old key.
The dashboard/backend last_used_at field changes after successful authenticated requests. It is not maintained locally by the SDK.