API Keys and REST API

What an API key is for#

An API key is a long-lived secret that identifies you to the Vastopia platform. The dashboard signs you in with your browser session; everything that runs outside the browser uses a key instead:

• The Vastopia Editor, when you sign in by pasting a key rather than through the browser flow. Pushing builds, registering a game, syncing project sources and authoring store items all go through that key.
• The Vastopia MCP server, so an AI assistant can publish builds on your behalf.
• Your own scripts and tools that call the REST API directly: listing builds, checking whether a game is live, automating a deploy.

A key carries your whole account. Anyone who holds it can do anything you can do through the API, so treat it like a password.

Manage keys on the dashboard#

API Keys lives in the dashboard sidebar under Account (/settings/api-keys) and is also reachable from the profile dropdown in the header. The page reads "Manage API keys for the Vastopia Editor. Paste a key into the editor to connect your account."

Generate a key#

1. In the Generate New Key card, type a name in the field labeled "Key name (e.g. My Editor Key)". Name it after where it will live, such as Laptop editor or CI deploy script, so you can revoke the right one later.
2. Click Generate.
3. A green card appears: "Key created! Copy it now — you won't see it again." Use the copy button next to the key and store it somewhere safe.

The full key is shown exactly once. The platform stores only a hash, so it cannot be retrieved later; if you lose it, generate a new one and revoke the old one.

Review and revoke#

Each key card lists the name, prefix, Created date and, once it has been used, a Last used date (updated on each authenticated request, best effort). An empty page says "No API keys yet. Generate one to connect the editor."

To revoke a key:

1. Click Revoke on its card.
2. The Revoke API Key dialog warns: "This will immediately revoke this key. Any editor sessions using it will be disconnected."
3. Click Revoke Key.

Revocation is immediate and permanent. An editor signed in with that key gets a 401 on its next request and must sign in again.

Session keys#

The editor can mint a short-lived session key for processes it launches, such as its MCP server: POST /api/users/me/api-keys/session returns a user-scoped vst_ key that expires after 12 hours and is named "MCP session key" unless you pass a name. These show in your list until they expire; you can revoke them like any other key.

Connect the editor with a key#

The editor prefers the browser sign-in (Sign in opens the platform's hosted login), and a pasted key is the alternative when that flow is unavailable. Three places accept one:

Pasting a key makes the editor call GET /api/users/me with it; on success the key is saved to the editor's user data folder as vastopia_platform.cfg ([platform] api_key) and the editor is signed in as that account. A key that the platform rejects shows "Invalid API key". Sign Out in the Account Info dialog clears it.

Connect the MCP server with a key#

The Vastopia MCP server needs a key only for publishing tools (register_game, create_build, upload_build_artifacts, finalize_build, deploy_test_build, promote_build, rollback_build, update_game_listing and friends). Authoring tools work without one.

When VASTOPIA_API_KEY is unset, the MCP server falls back to the key the editor saved in vastopia_platform.cfg, so signing in to the editor once is enough. Without any credential the publishing tools are still listed but fail with a message telling you to set VASTOPIA_API_KEY. See MCP setup.

Call the REST API yourself#

The production base URL is https://vastopia-api-8a231eb9cc69.herokuapp.com/api. Every authenticated request carries the key in an x-api-key header:

curl -H "x-api-key: vst_your_key_here" \
  https://vastopia-api-8a231eb9cc69.herokuapp.com/api/users/me

The API also accepts the key as an Authorization: ApiKey <key> header, an apiKey query parameter or an apiKey field in a JSON body, but the header is the recommended form because it stays out of logs and URLs. Authorization: Bearer is reserved for browser and OAuth tokens; do not put an API key there.

Responses are JSON. Successful calls generally include "success": true; failures return an HTTP status with a message or error field:

Check who you are#

curl -H "x-api-key: $VASTOPIA_API_KEY" "$API/users/me"

Returns your profile (username, email and related fields). This is the same call the editor makes to validate a pasted key, so it is the quickest way to test one.

List your games and builds#

# Your games (newest first; supports ?page=, ?limit=, ?q=, ?tag=)
curl -H "x-api-key: $VASTOPIA_API_KEY" "$API/games/me"

# Builds for one game, newest first (add ?includeDeleted=true to see deleted ones)
curl -H "x-api-key: $VASTOPIA_API_KEY" "$API/games/$GAME_ID/builds"

Each build row includes buildId, buildNumber, buildName, status, pckSize, totalSize, versionLabel, promotedAs, patchNote, testServerHost/testServerPort while a test server is up, createdAt, promotedAt and failureReason. Statuses are uploading, ready, live, staged, superseded, beta, archived, deleted and failed; see Builds and versions.

Check live status (no key needed)#

curl "$API/games/$GAME_ID/live"

This endpoint is public. It returns the build players currently get: buildId, versionLabel, buildName, serverHost, serverPort, serverStatus, a one-hour presigned pckDownloadUrl, file sizes and SHA-256 hashes, deployedAt, isStaged, updateInProgress and the signature fields clients verify before mounting a pack. If a staged build exists it is preferred for new sessions; add ?prefer=live to ask for the live build instead. A game with nothing deployed answers 404 {"success":false,"error":"No deployed version"}.

Promote a build#

curl -X POST -H "x-api-key: $VASTOPIA_API_KEY" -H "Content-Type: application/json" \
  "$API/games/$GAME_ID/builds/$BUILD_ID/promote" \
  -d '{"type":"update","updatePost":{"title":"Combat Update","body":"Reworked melee hitboxes."}}'

type must be update or patch. An update may carry an updatePost (both title, up to 120 characters, and body, up to 20,000, or neither) or an updatePostId pointing at a draft; a patch may carry a patchNote. timing defaults to now. When deployment jobs are enabled the call returns 202 with a jobId, which you can follow with GET /games/{gameId}/deploy-status. The dashboard's Update tab is the same call with a form in front of it; see Updates, patches and rollback.

Endpoint reference#

All paths are relative to the base URL. "Owner" means the key's account must own the game; most game-scoped routes check ownership rather than team role.

Account and keys#

Games#

Builds and deployment#

Shop, creator economy and revenue#

Keep keys safe#

• Never commit a key to a repository or paste it into a shared chat. If one leaks, revoke it on the dashboard immediately and generate a replacement.
• Use one key per machine or tool and name it accordingly; revoking a single key then disconnects only that device.
• Prefer the browser sign-in in the editor and the editor-credential fallback in the MCP server, so the secret exists in one place on disk.
• The platform keys automatically provisioned for your game servers (srv_) cannot act as you, but revoking them affects your running server, so leave them alone.
• Account deletion under Privacy & Account removes every key with the account.

With AI (MCP)#

There is no MCP tool for managing keys; generate one on the dashboard or let the MCP server reuse the editor's sign-in. The publishing tools that consume the key are register_game, create_build, upload_build_artifacts, upload_pck_multipart, finalize_build, deploy_test_build, stop_test_server, get_deploy_status, wait_for_deploy, list_builds, promote_build, rollback_build, get_live_status and update_game_listing. See the MCP tools reference.