Skip to main content
An API key (ibk_...) is how code, CI jobs, and agents call InstaBox: the HTTP API, the SDK, the CLI, and SSH all accept one. People sign in with GitHub or Google to use the dashboard and to make keys.
Send the key as X-API-Key: <key> or Authorization: Bearer <key>. The CLI and the SDK read the key from INSTABOX_API_KEY, and the server from INSTABOX_API_URL (default https://api.instabox.sh). With the key set, the CLI needs no instabox login.

​
Make a key

Choose API keys in the sidebar, then Create Key (dashboard.instabox.sh/dashboard/api-keys). Full access suits the SDK, and Restricted picks scopes. The key belongs to the workspace selected in the sidebar.
You see the secret once. Only a sign-in makes and revokes keys, so a key never makes another key. Revoking a key also ends its SSH certificates.

​
Pick a key’s scopes

Write and delete include read. Without --scope, instabox keys create gives a personal key machines:read, machines:write, machines:delete, and images:read, and a workspace key workspace:admin.
Give images:read to keys that create machines. The SDK and CLI use it to look snapshot names up.
A key with machines:write can select Org Secrets for a machine and run code there, and that code can send the selected Secrets to their allowed hosts. For a new machine that should get credentials from neither store, pass "vault": false, "secrets": [] on create.

​
Which workspace a key reaches

Every key belongs to exactly one workspace and reaches nothing outside it.
  • A key made with instabox keys create (no --org), with POST /v1/keys, or on API keys with your personal workspace selected belongs to your personal workspace. One made with --org W, with POST /v1/orgs/{id}/keys, or with W selected belongs to W.
  • Machines a key creates go in its workspace. Other workspaces’ machines, snapshots, and settings are 404 to it, and so is a create naming another workspace’s orgId.
  • To work in another workspace, use a key of that workspace, which its owner or an admin makes. Only a sign-in reaches every workspace you belong to (instabox create --org W).
  • To see a key’s workspace, call GET /v1/orgs (instabox workspace ls) with it. It lists that one workspace. GET /v1/me also has orgId for a workspace key.

​
Key errors

A bad key gets a 401 whose error.code says why: missing_key, malformed_key, invalid_key, expired_key, or revoked_key. A key without the scope a route needs gets 403 missing_scope, and requiredScopes names the scopes that route accepts. See Errors.

​
What a key cannot do

Some routes take a sign-in (instabox login or the dashboard) and refuse any API key with 403 permission_denied (“API keys cannot be used on this route”). They cover managing API keys, your Vault, GitHub CI installations and jobs, creating and deleting workspaces, billing, and sessions. A workspace’s Org Secrets take a workspace:admin key instead. To set up CI, install the GitHub App from the dashboard (CI).
  • API keys: GET /v1/keys, POST /v1/keys, DELETE /v1/keys/{id}, GET /v1/orgs/{id}/keys, POST /v1/orgs/{id}/keys, DELETE /v1/orgs/{id}/keys/{keyId}
  • Vault: GET /v1/vault, PUT /v1/vault/{name}, PATCH /v1/vault/{name}, DELETE /v1/vault/{name}, POST /v1/vault/import, POST /v1/vault/{name}/export
  • GitHub CI: GET /v1/orgs/{id}/github/installations, DELETE /v1/orgs/{id}/github/installations/{installationId}, GET /v1/orgs/{id}/github/jobs, GET /v1/orgs/{id}/github/jobs/{job}, GET /v1/orgs/{id}/github/stats
  • Workspaces and billing: POST /v1/orgs, DELETE /v1/orgs/{id}, PATCH /v1/orgs/{id}/billing, POST /v1/orgs/{id}/billing/checkout, POST /v1/orgs/{id}/billing/portal, POST /v1/orgs/{id}/billing/plan, POST /v1/orgs/{id}/billing/credits/subscribe, DELETE /v1/orgs/{id}/billing/subscription, POST /v1/orgs/{id}/billing/subscription/resume
  • Sessions: GET /v1/sessions, DELETE /v1/sessions/{id}
The API reference lists every route a key can call.

SDK quick start

Use the key from TypeScript or HTTP.

Agent sign-up

An agent gets its own key, approved by you.