API tokens
Everything you can do in the dashboard — launch an instance, list them, read connection details, start and stop, back up, query — is backed by the same API. Workspace tokens let you call it from scripts, CI, and AI agents.
Create a token
From your workspace, open API tokens and create one. Give it a name and copy the value immediately — it's shown once, and the list only ever shows the first few characters afterwards. Revoke a token any time from the same page; it stops working immediately.
Every token expires — choose 30, 90 or 180 days, or a year at most; the list shows each token's date. A token also stops working as soon as the person who created it leaves the workspace, is suspended, or moves to a role that no longer covers what the token can do. Tokens created before this rule have no recorded creator: they keep working until 16 November 2026 and then stop. The list marks each one with that date, and the workspace's owners and admins get one email about them; create a new token to replace each one. A kubeconfig's renewal token records who it was made for, so it isn't affected.
Scope it
A token doesn't have to inherit everything you can do. The create dialog lists the platform's resources — instances, web apps, networks, volumes, domains, SSH keys, certificates, load balancers, Kubernetes clusters, tokens — and the actions on each, and you pick exactly the ones this token needs:
| Resource | Actions |
|---|---|
instance | create, read, update, delete, lifecycle, backup, query |
project | create, read, update, delete |
network, volume, domain | create, read, update, delete |
certificate, loadbalancer | create, read, update, delete |
kubernetes | create, read, update, delete |
sshKey | create, read, delete |
apiKey | create, read, update, delete |
lifecycle (start/stop/restart) and query (running SQL) are separate from plain CRUD on purpose: running a box and running a statement against it are different risks from reading its metadata, and a deploy script usually wants one without the other.
read is metadata only — status, addresses, metrics, logs. It never reaches the data or the secrets: running any SQL, a SELECT included, takes query; the password in an instance's connection details and the values of an app's secret variables take update (a read-only token gets them masked); exporting a database, listing its exports and downloading a game server's files take backup.
The kubernetes actions manage clusters, their node pools and volumes. A token never gets a kubeconfig, never reads inside a cluster, never changes who has access to one or who can reach its API, and never turns off a cluster's deletion protection: those need a person signed in.
Two rules constrain what you can mint:
- A token can never exceed the role that created it. Your selection is intersected with your own role — a viewer's token reads, whatever the checkboxes said.
- A token never carries workspace-management rights. It cannot invite members, change roles, or delete the workspace that issued it, no matter who minted it.
Give the token an expiry — anything up to a year — and it stops working on its own if you forget it. A CI token that outlives the pipeline it was written for is the one most likely to leak.
Use it
Attach it as the x-api-key header on your requests:
curl "https://api.sahabti.com/v1/servers?orgId=$WORKSPACE_ID" \
-H "x-api-key: $SAHABTI_TOKEN"
Creating an instance is the same shape:
curl -X POST https://api.sahabti.com/v1/servers \
-H "x-api-key: $SAHABTI_TOKEN" \
-H "Content-Type: application/json" \
-d '{"engine":"postgres","name":"orders","plan":"small","orgId":"'"$WORKSPACE_ID"'"}'
The routes cover instances (create, list, get, start, stop, restart, rename, resize, retry, delete, connection details, provisioning log, metrics, quota usage, SQL query, inbound rules, public access), backups, exports and imports, networks, domains, SSH keys, certificates, load balancers, Kubernetes clusters, web apps and their deployments, and quota increase requests. A public API reference is not available yet.
Writes record intent and answer immediately — the platform then reconciles to it. A script that creates an instance should poll the instance back until it's running, not assume the next line can connect to it.
A token acts as the person who created it. In a workspace that requires two-step verification, it works only while that person has two-step verification set up; otherwise every request answers 403 with TWO_FACTOR_REQUIRED, and starts working again once they set it up. Some older tokens don't record who created them — those stop working in such a workspace, so create a new one.
Next steps
- New here? Start with getting started
- MCP for AI agents — the same surface, spoken by Claude, Cursor, or your own agent
- Instances — what each lifecycle action does
- Workspaces & roles — the ceiling your token is capped at