Server API reference
Version 1 of the API your game backend calls: read your game's configuration, verify that a connecting player holds a live protected session, and end sessions.
Authentication
Send a game-scoped server key as a bearer token over HTTPS:
Authorization: Bearer obs_sk_...
Server keys are secrets for backend use only. A key maps to one game, and through it to one organization. Keys are rejected when revoked, expired, or when their game is archived. No request parameter can select another game.
POST /api/v1/sessions/verify
Redeem the join token a connecting client presented. Call this before you admit the player.
curl https://obscurity.ac/api/v1/sessions/verify \
-H "Authorization: Bearer obs_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"join_token": "obs_jt_...", "player_id": "your-account-id"}'
player_id is your own stable identifier for the account that is connecting (1 to 128 characters). Use an opaque account ID rather than an email address or display name.
{"valid": true, "code": "ok", "session": {"id": "ps_...", "status": "active", "player_id": "your-account-id", ...}}
{"valid": false, "code": "token_used"}
| Code | Meaning |
|---|---|
ok | The token is genuine, unused and unexpired, was issued for this game, and its session is running. |
token_invalid | Not a token Obscurity issued for this game. |
token_used | Already redeemed. A token works once; a second presentation is a replay. |
token_expired | Older than 60 seconds. The client asks the SDK for a new one. |
session_not_active | The session ended or timed out before the token was redeemed. |
player_mismatch | The session was already verified for a different player_id. A session belongs to the first player it is verified for. |
player_restricted | Someone on your team restricted this player from this game after reviewing evidence. The answer includes restriction.id and restriction.expires_at. Do not admit the player; tell them how to reach your support. See detections, review and restrictions. |
network_restricted | Only for a game taking part in the Global Ban Network: the player has an active, validated ban from another participating game. The answer includes restriction.id, restriction.penalty and restriction.expires_at. Do not admit the player. If they appeal and you agree, allow that shared ban for your game on the game page. See the Global Ban Network. |
POST /api/v1/sessions/{id}/events
Report actions your game server rejected in a session, up to 100 per call.
{"events": [
{"type": "movement.rejected", "at": "2026-11-15T04:30:12Z", "data": {"measured": 21.4, "allowed": 6.9}},
{"type": "rate.rejected", "data": {"action": "fire"}}
]}
at is optional (ISO 8601 or seconds since the epoch) and defaults to the time of receipt. The answer is {"accepted": n, "rejected": [{"index", "reason"}], "detections": [...]}. Reasons: unknown_type, invalid_data, feature_off (the game has reports switched off), session_limit. The event types and their fields are listed in detections, review and restrictions. A detection in the answer is a lead for your team to review, not a verdict.
GET /api/v1/detections
This game's detections, newest first. status is open (default), confirmed, dismissed or all; limit is at most 200. Each item has the detector and its version, the session and player, a summary, and the evidence with the thresholds that were used.
GET /api/v1/sessions/{id}
Current state of one of your game's sessions. Use it to re-check a connected player at an interval of your choosing.
| Field | Description |
|---|---|
status | active; stale (heartbeats are late: the client may be paused or offline); ended; expired (no heartbeat for five minutes). |
end_reason | Why it ended: client_ended, ended_by_game_server, timed_out, or an admission code if the game's policy or service state changed. |
policy | The profile, policy version and enforcement mode the session runs under. |
client.build_status | recognized, unrecognized or unchecked (no builds registered). The hash is reported by the player's PC: a signal, not proof. |
platform | The result for each platform item the game requires: satisfied, feature_disabled, hardware_unsupported, os_unsupported, verification_unavailable or evidence_invalid. In Enforce mode a verified session has every entry satisfied; in Monitor mode the entries are what was recorded. They are compatibility results: do not treat one as a finding about the player. See platform verification. |
development | true when the session runs under the development allowance of a game without a subscription. |
POST /api/v1/sessions/{id}/end
End a session when the player leaves or you remove them. Safe to call more than once. The client SDK is told at its next heartbeat.
GET /api/v1/game
Returns the game the key belongs to, its organization, the active protection policy and this month's usage. Use it to verify a key at deploy time.
| Field | Description |
|---|---|
game.id | Stable game identifier. |
game.status | development or live. |
policy.version | Number of the active policy version. Increases with every change. |
policy.profile | The protection tier the game requires: core, advanced or elite. |
policy.features | The game's feature switches: true or false for each switchable feature its tier includes (build_check; on Advanced also tpm20, secure_boot, hvci, iommu; on Elite also boot_component). Set in the console. |
policy.platform_requirements | For each platform feature the tier includes, required when its switch is on, otherwise not_required. Empty for Core. |
policy.boot_component | required on Elite when its switch is on, otherwise not_required. |
policy.enforcement | enforce or monitor. |
entitlement.access | Billing state of the game: active, grace, suspended, canceled or unsubscribed. This describes your account, never a player. |
entitlement.covers_policy | true when the paid tier is enough for the tier the policy requires. When false, protected sessions are refused rather than admitted under a weaker tier. |
usage | For the current UTC month: monthly_active_players (distinct verified player_id values), peak_concurrent_sessions, sessions_admitted, sessions_refused, and concurrent_now. |
credential.expires_at | Set when the key has been rotated and is in its overlap window; otherwise null. |
When Obscurity cannot be reached
A timeout, a 5xx or a 429 says nothing about the player. Decide in advance whether your game server admits or refuses players while verification is unavailable, and write that choice down in your code. The sample game server refuses by default and can be switched to admit.
Errors
Errors are JSON with a stable code and a human-readable message:
{"error": {"code": "unauthorized", "message": "Missing or invalid server key."}}
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | No key, or a key that is unknown, revoked or expired. The response does not say which. |
| 404 | not_found | Unknown endpoint, or a session that does not belong to this key's game. |
| 422 | invalid_request | A required field is missing or malformed. |
| 429 | rate_limited | Too many requests. Retry with backoff. |
Rate limits
- 600 requests per minute per key.
- 30 failed authentication attempts per 5 minutes per source address, after which that address receives 429 until the window passes.
Health probes
GET /healthz reports that the service process is running. GET /readyz reports whether its dependencies are reachable and returns 503 when they are not. Neither needs authentication.