Authentication
Every endpoint documented in this section except GET /v1/health requires a bearer token:
Authorization: Bearer <token>
Two kinds of credential
The same header accepts two credential types, and they do not have the same reach.
| Session token | API key | |
|---|---|---|
| Looks like | A JWT issued when you sign in to the console | shk_ followed by 48 hex characters |
| Where it comes from | The browser session, refreshed automatically | Created once under API Keys in the console |
| Lifetime | Short-lived; expires and refreshes | Until you revoke it |
| Role it acts with | Your real role in the organization, admin or member | Always member |
| Organization | Whichever one you select | Only the organization the key was created in |
Account endpoints (/v1/me, /v1/ssh-keys) | Allowed | Rejected with 401 TOKEN_INVALID |
| Admin actions, including billing | Allowed if you are an admin | Rejected with 403 ADMIN_REQUIRED |
Use an API key for anything that runs unattended. Session tokens expire, so a script that carries one stops working without warning. See API keys for how to create and revoke them.
curl -s "$SUPERHEAT_API/v1/instances" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
Choosing the organization
Instances, templates, balances and keys belong to an organization. The X-Org-Id header picks which one a request runs against:
| Header | Session token | API key |
|---|---|---|
| Absent | Your personal organization | The key's own organization |
| Set to an organization you belong to | That organization, with your role there | Allowed only if it matches the key's organization |
| Set to an organization you do not belong to | 403 NOT_A_MEMBER | 403 ORG_MISMATCH |
| Not a valid id | 400 INVALID_ORG_ID | 403 ORG_MISMATCH — a key compares the header against its own organization id before validating it |
curl -s "$SUPERHEAT_API/v1/instances" \
-H "Authorization: Bearer $SUPERHEAT_KEY" \
-H "X-Org-Id: 9c1b7d4e-3a52-4a1f-8c6d-b0e9f2a71c48"
List the organizations you can act in with GET /v1/orgs, which returns each one's id, name, personal flag, your role and the balance. That call needs a session token.
Failure modes
| Status | Code | Meaning |
|---|---|---|
| 401 | TOKEN_INVALID | Missing header, malformed token, unknown or revoked API key, or an API key sent to an account endpoint |
| 401 | TOKEN_EXPIRED | The session token is past its expiry — sign in again |
| 403 | NOT_A_MEMBER | The X-Org-Id organization is not one of yours |
| 403 | ORG_MISMATCH | The API key belongs to a different organization than X-Org-Id |
| 403 | ADMIN_REQUIRED | The action is admin-only, or you tried it with an API key |
| 400 | INVALID_ORG_ID | X-Org-Id is not a valid id on a session-token request |
Full response shapes are in Errors.
Anyone holding an shk_ key can deploy instances that spend your organization's balance. Keep keys out of source control and revoke any key you have pasted somewhere you cannot control.