API Keys

Open Dashboard → API Keys, choose a preset or custom scopes, and copy the generated secret. The secret is shown only once.

Every scope is enforced on every route. A key can only reach what its scopes allow — and only routes that are explicitly published to the API at all.

• catalog:read: browse GPUs and available machines
• instances:read: list and read instances, resources, status, events, runs, logs
• instances:create: deploy automation
• instances:manage: stop, delete, restart, reconfigure
• instances:exec: run commands inside a container — see below
• ports:manage: HTTP ports and raw TCP/UDP exposures
• vault:read / vault:write: browse and download / upload, rename, delete
• billing:read: payment history and billing settings
• org:read / org:manage: read the team / manage members and settings
• notifications:read: read and mark notifications
• reservations:manage: capacity queue reservations
• tickets:manage: open support tickets
• profile:read / profile:manage: read the account / change preferences (name, locale, notification settings)
• keys:manage: API key administration

The Upload token preset grants vault:write and nothing else. It reaches /vault over HTTPS with no instance running, so a script or CI job can push a dataset without booting.

It is deliberately write-only, because CI is the least trusted place a credential lives. A token leaked from there cannot deploy an instance, cannot start GPU spend, and cannot read or download a single file — vault:read is what reaches GET /vault/list and GET /vault/download-zip, and it is not in this preset.

curl -X POST "https://upload.gputw.ai/api/vault/upload?path=datasets" \
  -H "Authorization: Bearer gputw_live_..." \
  -F "[email protected]"

Send uploads to the transfer host, as above — it connects straight to storage instead of through the CDN, so a single request is not capped at 100 MB. The same route works on the main hostname under that cap. Files over 90 MB should use the resumable multipart API. See Vault Storage.

The one route that has to read a session — GET /vault/uploads/<id>, for resume and the completion poll — accepts either vault scope, so a write-only token still finishes what it starts. See Vault Storage for the full upload flow and the SCP alternatives.

Some actions are unavailable to API keys no matter which scopes the key holds, because no scope would make them safe to automate. Use a browser session for these.

• SSH keys: adding a key grants root SSH to every running instance on the account, which would escalate past any scope the key was issued with
• Account security: password change, email change, and account deletion
• Team creation and deletion: irreversible, with no automation use case
• Checkout: spends money and requires an interactive redirect
• Admin APIs: never available through a user API key

Rotate immediately if a key is exposed. Revoking a key stops future API access without affecting browser sessions.

Use the narrowest scope set that fits the automation. A deployment bot usually needs catalog:read, instances:read, and instances:create. A monitoring job that only reads utilization needs instances:read alone. Operational scripts that stop, restart, or delete instances need instances:manage.