Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/universeclouddev/Universe/llms.txt

Use this file to discover all available pages before exploring further.

Every request to the Universe REST API (except the open /ping and /metrics endpoints) must carry a valid API key. Universe uses Bearer token authentication — the key is passed as a plain string in the Authorization request header. Keys are created and managed directly from the Universe master-node console.

​
How It Works

When a request arrives the API reads the Authorization header, strips the Bearer prefix, and looks up the token in the database (with a 15-second in-memory cache to avoid hammering the database on every call). If the token is unknown or missing, the API returns 401 Unauthorized. If the token resolves to a PUBLIC key that has already exceeded its sliding window quota, the API returns 429 Too Many Requests. 
Authorization: Bearer YOUR_API_KEY

​
Permission Levels

Universe defines two permission levels in ApiPermission:
ALL keys have unrestricted access to every endpoint — instance creation and deletion, configuration management, template editing, console commands, and log streaming. They are also exempt from rate limiting entirely.Use ALL keys for automation pipelines, internal services, and trusted operator tooling.
ALL keys grant full control over your entire cluster. Treat them like root credentials — store them in secrets managers, never commit them to source control, and rotate them if they are ever exposed.

​
Generating API Keys

Keys are created and managed from the interactive console on the Universe master node. Open a console session and use the key commands:
1

Create an ALL key

Run the following command to create a full-access admin key named automation:
key create automation ALL
The console will print the generated bearer token. Copy it immediately — it is only displayed once.
2

Create a PUBLIC key

To create a PUBLIC-permission key (rate-limited; note that all protected routes require ALL — PUBLIC keys can only reach the open /ping and /metrics endpoints):
key create dashboard PUBLIC
3

List existing keys

View all active keys with their IDs and permission levels:
key list
4

Delete a key

Revoke a key by its ID:
key delete <id>
Deletion is immediate — in-flight requests using the revoked token will fail on their next cache miss (within 15 seconds).

​
Making Authenticated Requests

Pass the bearer token in the Authorization header of every HTTP request: 
curl -H "Authorization: Bearer YOUR_KEY" \
     http://localhost:7000/api/instances

curl -X POST http://localhost:7000/api/instances \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"configurationName": "lobby"}'

​
Rate Limiting

The rate limiter applies a sliding window algorithm per API key. A PUBLIC key may make at most 100 calls within any 60-second window. Once that limit is reached the API responds with 429 Too Many Requests and a JSON body telling you when to retry: 
{
  "error": "Rate limit exceeded",
  "message": "100 calls were already made during 1m",
  "retryAfterMs": 45000
}
The rate limiter reads the Authorization header directly in the onCall phase — before Ktor’s authentication interceptor runs — so the window check happens on every request with zero overhead from the auth pipeline.Requests from unauthenticated callers (missing or malformed Authorization header) are rejected immediately with 401 by the rate-limiting plugin before reaching any route handler. ALL keys skip the window check entirely and are always allowed through.
All protected API routes require an ALL key. Use PUBLIC keys only if you need a rate-limited credential scoped exclusively to the open /ping and /metrics endpoints. For any workflow that calls instance, configuration, template, cluster, node, or command endpoints, you must use an ALL key.

​
WebSocket Authentication

The two WebSocket endpoints (/instances/{id}/live-log and /console) require the same Bearer token in the HTTP upgrade request headers: 
# Live log stream
websocat -H "Authorization: Bearer YOUR_KEY" \
  ws://localhost:7000/api/instances/a1b2c3/live-log

# Interactive console
websocat -H "Authorization: Bearer YOUR_KEY" \
  ws://localhost:7000/api/console
Authentication is validated during the handshake. If the token is missing or invalid, 101 Switching Protocols is never sent and the connection is rejected with 401.
GET /api/ping and GET /api/metrics are the only two endpoints that do not require authentication. /ping returns basic node status and is safe to use for health checks. /metrics returns Prometheus exposition-format data intended for scraping.

​
Error Reference

​
401 Unauthorized
object
Returned when the Authorization header is absent, malformed, or contains an unknown token.
{ "error": "Unauthorized" }
​
429 Too Many Requests
object
Returned when a PUBLIC key exceeds 100 requests in a 60-second window. Because all protected routes require ALL permission, this response is only reachable via the open endpoints (/ping, /metrics) where the rate-limiting plugin still tracks PUBLIC key usage.
{
  "error": "Rate limit exceeded",
  "message": "100 calls were already made during 1m",
  "retryAfterMs": 45000
}

Build docs developers (and LLMs) love

Get started for freeTalk to us