API keys¶
API keys authenticate programmatic access to Sistemo Cloud. Pass one as a Bearer token on every request:
The SDKs read the key from the SISTEMO_API_KEY environment variable automatically.
Create a key¶
- Dashboard → API Keys → Create key.
- Give it a name (e.g.
ci-pipeline,agent-prod). - Choose a scope (see below).
- Optionally set an expiry.
- Copy the
sk_live_…secret — it is shown only once. Store it in a secret manager.
If you lose a key, revoke it and create a new one — the secret cannot be retrieved again.
Scopes¶
| Scope | Can do | Cannot do |
|---|---|---|
| read | List/get machines, list volumes, view usage | Create sandboxes, run code, mutate anything |
| full | Everything read can, plus create/stop/start/destroy machines, run code (exec), manage volumes, checkout | — |
Exec needs full
Running code (sandbox.run) requires a full key, because it executes commands. Use read keys for dashboards, monitoring, or read-only integrations.
Key management itself (creating and revoking keys) is dashboard-only — it can't be done with an API key, the same model Stripe uses.
Lifecycle¶
- Revoke — a key stops working immediately. Done from the dashboard.
- Expiry — optional; an expired key is rejected like a revoked one.
- Last used — the dashboard shows an approximate last-used time so you can spot stale keys.
- Limit — up to 50 active keys per account.
Security model¶
- Keys are
sk_live_followed by 256 bits of random — high entropy, not guessable. - Only an HMAC-SHA256 hash of the key is stored, under a server-side pepper. A database dump alone cannot recover your keys.
- The full secret is shown once at creation and never stored, logged, or returned again.
- Any invalid, revoked, or expired key returns a generic
401— no information leak.
Rotate regularly
Treat keys like passwords: one key per app/environment, rotate periodically, and revoke immediately if a key may have leaked. Sistemo's sk_live_ prefix is designed to be caught by secret scanners.