Admin API Reference

The Admin API is a REST API for developer tooling — registering games, rotating keys, checking usage, and monitoring Worldweave connection status. It is not a game client API. Game clients never call the Admin API; they authenticate via the WorldweaveClientConfig API key and communicate through the Worldweave client SDK.

Base URLs

Environment	Base URL
Production	`https://root.softfire.dev/admin`
Development	`https://root-dev.softfire.dev/admin`

Authentication

All Admin API requests require a Bearer JWT in the Authorization header. Obtain a JWT from POST /auth/developer/login:

POST /auth/developer/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your-password"
}

Response:

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-05-15T14:30:00Z"
}

Include the token in subsequent requests:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

JWTs expire after 24 hours. Re-authenticate to obtain a new token. Tokens can be revoked from the developer portal (Account → Active Sessions).

Rate limits

60 requests per minute per developer account, measured in a rolling 60-second window. Exceeding the limit returns HTTP 429 with a Retry-After header.

OpenAPI specification

The full interactive specification is available at:

https://root.softfire.dev/admin/openapi.json

Import it into Insomnia, Postman, or any OpenAPI-compatible client for a complete interactive reference with request/response schemas.

Endpoints

Authentication

Method	Path	Description
`POST`	`/auth/developer/login`	Authenticate with email and password, receive a JWT
`POST`	`/auth/developer/logout`	Revoke the current JWT
`POST`	`/auth/developer/refresh`	Exchange a valid JWT for a new one before expiry

Games

Method	Path	Description
`GET`	`/games`	List all games registered to the authenticated developer account
`POST`	`/games`	Register a new game
`GET`	`/games/{id}`	Get details for a specific game
`PATCH`	`/games/{id}`	Update a game’s display name, description, or platform targets
`DELETE`	`/games/{id}`	Soft-delete a game registration (does not revoke existing player sessions)

Usage

Method	Path	Description
`GET`	`/games/{id}/usage`	Get current month MAU count, daily breakdown, and tier ceiling
`GET`	`/games/{id}/usage/history`	Get MAU history by month for the last 12 months

API Keys

Method	Path	Description
`GET`	`/games/{id}/keys`	List all API keys for the game (keys are masked; only the last 4 chars shown)
`POST`	`/games/{id}/keys/rotate`	Generate a new API key; old key remains valid for a 24-hour overlap window
`POST`	`/games/{id}/keys/{keyId}/revoke`	Immediately revoke a specific key with no overlap window

Notifications

Method	Path	Description
`GET`	`/games/{id}/notifications`	List recent platform notifications for the game (MAU ceiling alerts, outage notices, billing alerts)
`PATCH`	`/games/{id}/notifications/{notifId}`	Mark a notification as read

Worldweave Status

Method	Path	Description
`GET`	`/games/{id}/Worldweave/status`	Get the current Worldweave connection status for a game: tier, MAU ceiling, active Strand regions, Living World simulation health

Request and response format

All request bodies are JSON with Content-Type: application/json. All responses are JSON. Error responses follow the RFC 9110 Problem Details format:

{
  "type": "https://root.softfire.dev/errors/rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "60 requests per minute limit reached. Retry after 12 seconds.",
  "retryAfter": 12
}

Example: Get current MAU usage

GET /games/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/usage
Authorization: Bearer eyJ...

Response:

{
  "gameId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "billingPeriod": {
    "start": "2026-05-01T00:00:00Z",
    "end": "2026-05-31T23:59:59Z"
  },
  "tier": "Indie",
  "ceiling": 10000,
  "currentMau": 4231,
  "ceilingReachedAt": null,
  "dailyBreakdown": [
    { "date": "2026-05-01", "newMau": 142 },
    { "date": "2026-05-02", "newMau": 218 }
  ]
}