Authentication

All /api/* requests authenticate with an HTTP token in the Authorization header. Both the Token and Bearer schemes are accepted:

Authorization: Token {{ SuperSpace API Token }}

Authorization: Bearer {{ SuperSpace API Token }}

There are three credential types, all presented the same way. The server resolves which kind it is (session / API key first, then OAuth):

IP Restriction

You may restrict access by IP to a particular API Key in the SuperSpace API Key Manager. Note that when you attempt to connect from a non-authorized IP, you will receive the same response as if you supplied an invalid API Key.

By default there is no IP restriction in place.

Setting Account Scope

Some API endpoints require an Account Scope. To specify which account you would like to be working under, include the header X-Auth-Account set to your Account ID:

X-Auth-Account: {{ SuperSpace Account ID }}

Behavior:

• For a user API key, X-Auth-Account scopes the request to a single account and sets the account context. Without it, list endpoints return resources across all accounts the key's user can access.
• Some endpoints require it and return 400 {"errors":["Missing X-Auth-Account"]} when it is absent — Orders, Carts, Subscriptions, Users, Webhooks, DNS-zone create, and all Domain Registration endpoints.
• OAuth tokens always carry an account, so the header is ignored for them.

Authentication Failures

A failed authentication returns 401 with the header WWW-Authenticate: Token realm="Application" and an empty body. Causes include no/invalid token, an IP not on the key's access list, a trial account, or an X-Auth-Account value that doesn't match an account the token can access.

{ "error": "invalid_token", "error_description": "token audience is not valid for /api" }

Conventions

• All API routes are under /api/. All responses are JSON.
• Resource IDs are GUIDs, except numeric task IDs, integer volume IDs, integer DNS record-type codes, and numeric domain_contact IDs.
• Timestamps are ISO 8601, UTC.
• Async operations return 202 Accepted — poll a task, registrar process, or cart to check completion (see Async Operations).

Pagination

Index endpoints accept page and per_page query parameters.

Rate Limiting

Requests are limited to 600 per 10 minutes, per credential. Exceeding the limit returns 429 with an empty body.

Error Responses

Async Operations

Most provisioning operations are asynchronous and return 202 Accepted with a reference to poll.

• Tasks — PHP version changes, backups, restores, restart, site-domain add/remove, cache changes, account-role removal, and account deletion create a Task. Poll GET /api/tasks/:id or GET /api/sites/:site_id/tasks/:id. Task statuses: PENDING, RUNNING, OK, FAILED, CANCELLED, PAUSED.
• Carts — site creation (POST /api/orders), site resize / plan-change (PATCH /api/sites/:id with plan), and domain orders (POST /api/orders/domain) are polled via the cart, not a task: they return a cart envelope; poll the cart for materialized orders.
• Registrar processes — domain-registration mutations may open a process; poll it for completion.

Completion Callback

Order creation accepts an optional callback so you receive a webhook when the async work finishes instead of polling:

{ "callback": { "url": "https://your-app.com/webhook", "authorization": "Bearer your-secret" } }

See Callbacks for the full contract.

About Endpoint

SuperSpace offers an 'about' endpoint that provides information about who you are logged in as, as well as information about available resources. It accepts any valid token regardless of OAuth scope.

GET /api/about

curl -H "Authorization: Bearer $SUPERSPACE_TOKEN" \
  https://your-instance/api/about