Skip to content

Developer tools: API and MCP

SuperSpace is built around a single REST API. Everything the dashboard does — provisioning sites, editing DNS, configuring the CDN and Shield, reading metrics — goes through that same API. You can call it yourself to automate work or build an integration, and you can let an AI assistant call a curated subset of it through the MCP server.

The short version

  • The REST API is a set of JSON-over-HTTP endpoints under /api. You call it from scripts, your own apps, or the command line.
  • The MCP server (POST /mcp) exposes a hand-picked set of the API as tools that AI assistants can call on your behalf.
  • You authenticate the REST API with an API key you create in the dashboard, or with an OAuth access token. The MCP server is OAuth-only.
  • Start with the API overview for the REST API, or Connecting to MCP to wire up an assistant.

How the API and MCP relate

The REST API is the foundation. The MCP server sits on top of it and re-uses the exact same backend — when an assistant calls an MCP tool, SuperSpace runs the same logic and returns the same data as the matching REST endpoint. The difference is who's driving and how the surface is shaped:

REST API MCP server
Who calls it Your scripts and integrations AI assistants (LLM clients)
Endpoint /api/... (many endpoints) A single POST /mcp endpoint
Shape HTTP routes and JSON bodies Named tools the assistant picks from
Sign-in API key or OAuth token OAuth token only
Coverage The full API surface A curated subset — broad reads, a few safe writes

The practical takeaway: if you're writing code, use the REST API directly. If you want Claude (or another assistant) to read and adjust your SuperSpace account in conversation, connect it to MCP — you don't write any HTTP yourself, the assistant calls the tools for you.

The REST API

The REST API covers sites, domains, DNS, the CDN and cache, Shield (the WAF/DDoS/bot protection layer), backups, metrics, orders, and more. Requests are plain HTTPS with a JSON response. A read looks like this:

curl -H "Authorization: Bearer $SUPERSPACE_TOKEN" \
     -H "X-Auth-Account: $ACCOUNT_ID" \
     https://control.superspace.nl/api/sites

The X-Auth-Account header tells SuperSpace which workspace the request applies to — you'll find this value (your Account ID) on the same dashboard screen where you create API keys. OAuth tokens already know their workspace, so they don't need this header.

Where to go next

The API overview is the full reference: authentication, every endpoint, request and response shapes, and error codes. This page is just the orientation.

Authenticating with an API key

The simplest way to call the API is with an API key — a long-lived token you create in the dashboard and send on every request. To create one:

  1. Open the avatar (user) menu and choose My Settings. In the settings sidebar, under the Developer section, choose API Keys.
  2. Give the key a name and select Create API Key.
  3. Copy the token immediately — for security it's shown only once. The same screen shows your Account ID (Workspace) with a copy button; that's the X-Auth-Account value your requests need.

You can revoke a key at any time from that same API Keys screen, which lists each key's name, when it was created, and when it was last used.

Treat API keys like passwords

An API key has the same access you do in that workspace and is not scope-limited. Anyone holding it can act as you. Store keys somewhere secure, never commit them to source control, and revoke any key you suspect has leaked.

Trial workspaces can't use the API

The API and MCP server reject any credential that resolves to a trial workspace. Upgrade to a paid plan to use developer tools.

Reviewing API activity

The dashboard keeps a log of requests made with your personal API keys. Under the same Developer sidebar section, open API Request Logs to see each request's timestamp, the key used, the HTTP method, the URL, and the originating IP address. This is useful for confirming an integration is working and for spotting requests you didn't expect.

Authenticating with OAuth

OAuth is the right choice when a third-party app needs to act on your behalf and you don't want to hand it a raw API key. Instead of pasting a key into someone else's product, you click through a SuperSpace sign-in screen, pick which workspace the app may touch, and approve a specific list of permissions (called scopes). The app receives a token limited to exactly what you approved — for example, read-only access to your sites and DNS but nothing that spends money.

OAuth tokens are deliberately more limited than API keys: they're confined to the scopes you granted, they're locked to one workspace, and some sensitive actions (such as placing paid orders) can't be done with an OAuth token at all. See OAuth 2.1 for the scope list and the full authorization flow.

Only paid workspaces appear in the picker

When you authorize an app, SuperSpace shows a picker of the workspaces you can grant access to. Trial workspaces don't appear there. If you have no paid workspace on the current site, you'll see a No eligible workspace page instead — upgrade a trial workspace or create a paid one first.

The MCP server

MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools. SuperSpace runs an MCP server so an assistant can manage your sites, DNS, domains, CDN, and Shield through normal conversation — you ask in plain language, and the assistant calls the right tools.

What you can do through MCP is a curated subset of the REST API: broad read access (list and inspect sites, DNS records, CDN and Shield status, metrics, orders, and subscriptions) plus a small set of safe writes (for example renaming or restarting a site, editing DNS records, purging the CDN cache, and adjusting Shield rules). The assistant only ever sees the tools your granted permissions allow, so a read-only authorization can't be used to change anything.

A few things are intentionally not available through MCP — most notably anything that spends money, such as placing an order. Those stay on the API-key path.

Getting connected

Modern assistants connect to SuperSpace directly over the internet — no local install or config file. You point your client at the MCP URL (https://control.superspace.nl/mcp) and authorize in the browser, exactly like the OAuth flow above. The step-by-step setup for specific clients is in Connecting to MCP.

MCP is OAuth-only

The MCP server does not accept API keys — every connection authorizes through OAuth so you can scope what the assistant may do and revoke it later. The token is also tied to the exact SuperSpace host you authorized against, so a white-label brand uses its own MCP URL.

Which one should I use?

  • Automating a task or building an integration? Use the REST API with an API key. Start at the API overview.
  • Letting another company's app touch your account? Use OAuth so you can grant limited, revocable access. See OAuth 2.1.
  • Working with an AI assistant? Connect it to the MCP server. See Connecting to MCP and the MCP reference.