Authentication
Every API request carries one credential in the Authorization header, either a personal API key or an access token from your own sign-in.
Personal API keys
A personal API key acts as you, with the permissions you choose for it. Use one for scripts, CI jobs and your own tools.
Create one in the console under your account settings, or with the API from a signed-in session:
curl -X POST https://api.sandscale.dev/api/v1/account/api-keys \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "ci", "scopes": ["sandboxes:create"], "expires_at": "2027-01-31T00:00:00Z"}'
The answer contains the key (it starts with nia_) once. It is never shown again, so store it in your secret manager straight away.
The rules the server enforces:
- Scopes. A key can only hold permissions you hold yourself when you create it. Asking for more is refused with
403 scope_exceeds_creator. - Expiry. Every key must have an
expires_at, at most 90 days ahead. - Number of keys. You can hold up to 10 live keys. One more is refused with
409 personal_key_limit. - Only you. Keys are created, rotated and revoked from your own signed-in session. An API key cannot create or rotate a key (
403 person_required).
Send the key as a bearer token:
curl https://api.sandscale.dev/api/v1/sandbox/instances \
-H "Authorization: Bearer $SANDSCALE_API_KEY"
Rotate and revoke
POST /api/v1/account/api-keys/{id}/rotate issues a new key with the same name and scopes. Pass overlap_seconds to keep the old key working for a while so you can roll it out. Rotation asks you to confirm it is you, so do it from the console. DELETE /api/v1/account/api-keys/{id} revokes a key at once. GET /api/v1/account/api-keys lists your keys with their state (active, expired or revoked); it never returns a secret.
Your own sign-in
The console and the CLI sign you in at auth.sandscale.dev with OAuth 2.0 and OpenID Connect: the authorization code flow with PKCE in a browser, or the device authorization grant (sandscale login --device) where no browser is at hand. The access token they hold is short-lived and refreshed with a refresh token.
The discovery document is at https://auth.sandscale.dev/.well-known/openid-configuration. The endpoints are listed under Sign-in and OAuth.
The CLI keeps its tokens in your operating system’s credential store and never prints them. To call the API from a script, create a personal API key rather than reusing the CLI’s session.
Coding agents
An agent connected with sandscale mcp runs the CLI’s commands with your sign-in, so it gets no credential of its own and can do only what you can. Agent Cloud tasks run under a grant you give from your own session, which you can end at any time.
Confirming it is you
Some changes, such as rotating a key, widening a policy or changing who may use an agent account, ask you to confirm it is you with a passkey, an authenticator app or an emailed code. The API answers them with 403 elevation_required until you do. Make these changes from the console, which asks for the confirmation and repeats the request for you.