API reference and integration guide
How an app connects to DartXchange. Everything on this page describes API behaviour that is implemented and has been exercised between two independent demonstration apps in a private staging environment.
dxk_ExampleKeyId0001 below are placeholders, never real credentials. Anything not described here (friends, invitations, spectators, video) does not exist.- Steps to integrate
- Signing
- Player sessions
- Lobbies
- Shared 501 match
- Errors
- Rate limits
- Testing
- Browsers and CORS
Steps to integrate
- Register a developer account, verify your email and wait for DartXchange to approve it.
- Register your application (name, short description, website, optional logo). DartXchange reviews it; on approval it gets a permanent app reference (for example
AB). You cannot choose or change it. - Create credentials in your dashboard. The secret is shown once: store it in your server’s secret store. Rotate by creating a second key, switching over, then revoking the old one (two can be active at a time).
- Sign your server’s requests (section below) and create a player session when one of your players wants to play across apps.
- Use the lobby and match endpoints with the short-lived player token.
- Watch your integration status in the dashboard. It moves forward only when DartXchange itself records the events: a signed session from your app, a lobby you hosted, a pairing with a different app, and a cross-app match played to a finish. Having credentials is not an integration.
- Optionally apply to be featured. Once your checks have passed you can ask for a public listing as an Approved Partner. Listing is optional and reviewed.
Signing your requests
Only your server signs, and the secret must never reach a browser, URL, repository or log. Every call that uses your app credentials carries four headers:
| Header | Value |
|---|---|
X-DX-Key-Id | Your key id: dxk_ + 16 characters |
X-DX-Timestamp | Unix time in seconds (10 digits), within 300 seconds of DartXchange’s clock |
X-DX-Nonce | 16–64 characters of A-Za-z0-9_-, new for every request (a repeat is 401 replayed_request) |
X-DX-Signature | base64url(HMAC-SHA256(key, canonical)), 43 characters, no padding |
The HMAC key is the 32 bytes you get by base64url-decoding the text after dxs_ in your secret (not the secret text itself). The canonical string is eight lines joined with \n, UTF-8, no trailing newline:
DX1-HMAC-SHA256
POST the HTTP method, upper case
/v1/auth/player-sessions the path, no query
the canonical query (empty line if none)
1763380000 the timestamp (same text as the header)
<nonce> same text as the header
<sha256 of the body, hex> of the exact bytes you send (empty body: e3b0c442...b855)
dxk_ExampleKeyId0001 the key id
Query rule: decode as a form query (+ is a space), re-encode with RFC 3986 (only A-Za-z0-9-._~ stay; everything else is %XX in upper-case hex), sort by name then value, join with &. Body rule: serialise your JSON once and sign those exact bytes.
Check your implementation against the published test vectors (eight cases, a test-only key that signs nothing real) and the reference signer (Python, standard library only). Reproduce every canonical string and signature byte for byte before you call the API. Common mistakes: + in a query, lower-case hex in %c3%a9, using the secret text as the key, padding on the signature, re-serialising the JSON after hashing it, reusing a nonce.
If a signed request is refused: 401 missing_credentials, malformed_credentials, timestamp_out_of_range, invalid_credentials (an unknown key and a wrong secret deliberately look the same) or replayed_request; 403 key_revoked, key_expired or app_suspended (only said to someone who proved they hold the key).
Player sessions
Your server asks for a session when one of your players wants to play across apps, and again about every 8 minutes while they stay. Your app authenticates its own players; DartXchange never sees their passwords.
POST /v1/auth/player-sessions (signed, server to server)
Content-Type: application/json
{ "external_player_id": "1001", your own stable id for the player (never returned)
"username": "180King", their name in your app (casing kept)
"scoring_method": "automatic" } "automatic" or "manual"
201 Created
{ "data": { "player_token": "dxp_...", "expires_at": 1763380600000, "refresh_after_seconds": 480,
"player": { "id": "pl_...", "username": "180King", "display_name": "180King-AB", "app_ref": "AB" } },
"request_id": "req_..." }
- The token lasts 10 minutes. Your app reference comes from your credentials, never from the request. Only these three fields are accepted.
scoring_methodis your app’s own statement: automatic means your app detects and calculates scores itself (even if the player can correct errors); manual means the player enters scores. Lobbies can require one or accept either.- Usernames are unique within your app, ignoring case (
409 username_conflict); the same name may exist in other apps. - End a session:
DELETE /v1/auth/player-sessionswithAuthorization: Bearer dxp_....
Lobbies
Every lobby call uses Authorization: Bearer dxp_.... The player, app and scoring method always come from the token; a body field or path can never name another player. Joining is request-and-accept.
| Call | What it does |
|---|---|
POST /v1/lobbies | Host a game: { "start_score": 501, "mode": "first_to", "legs": 1, "accepts": "either" } (accepts: automatic, manual or either; the host’s own method must satisfy it). Returns 201 { lobby_id, expires_at, reused }. Repeating identical settings is safe (reused: true). One active hosted lobby per player. |
GET /v1/lobbies?limit=20 | Open lobbies from active apps, each with the host’s display name and app reference, compatible for the caller, and my_request. |
GET /v1/lobbies/{id} | The lobby as this caller may see it. The host also sees join requests (the only place a player id is returned). |
POST /v1/lobbies/{id}/requests | Ask to join. A lobby whose scoring requirement you do not meet is refused with 409 scoring_not_accepted. |
DELETE /v1/lobbies/{id}/requests | Withdraw a request, or leave after being accepted. |
POST /v1/lobbies/{id}/requests/{player_id}/accept · .../reject | The host answers a request. Both players then see the pairing. |
POST /v1/lobbies/{id}/heartbeat | Host keeps an open lobby alive (5 minutes at a time, up to 30 minutes of waiting). |
POST /v1/lobbies/{id}/cancel · /close | The host cancels an open lobby; host or guest ends a matched game. |
GET /v1/me/lobby | Your player’s own active lobby, or { "lobby": null, "last_match": ... }. Use it to recover after a page reload, including a result the other player closed first. |
The shared 501 match
DartXchange owns the score of a game between the host and the accepted guest, so both apps always show the same state. One 501 leg (the lobby’s start score), host throws first, double out. Apps read the state and submit their own player’s visit totals.
GET /v1/lobbies/{id}/match
POST /v1/lobbies/{id}/match/turns
{ "score": 100, "finished_on_double": false, "expected_version": 0 }
scoreis the visit total, 0–180.expected_versionis theversionyou last read: a retry or double click is refused with409 stale_versioninstead of being applied twice.- A bust (over the remaining score, leaving 1, or reaching 0 without a double) leaves the score unchanged and passes the turn. Going out needs
finished_on_double: true(the bull counts). Totals that cannot be a finish (above 170, 159, 162, 163, 165, 166, 168, 169) are400 invalid_checkout. 409 not_your_turn,409 match_finishedand409 not_matchedare the other rule errors. The finished match stays readable by both players after the lobby closes.
Errors
Errors look like { "error": { "code": "...", "message": "..." }, "request_id": "req_..." }. Quote the request_id when you ask for help. Unknown failures are a generic 500.
| Status | Codes | Meaning |
|---|---|---|
| 400 | invalid_json, invalid_content_type, unknown_field, invalid_username, invalid_external_player_id, invalid_scoring_method, invalid_query, invalid_checkout | The request is not acceptable. Only documented fields are allowed. |
| 401 | signing codes above, invalid_token | Signing problem, or a bad, expired or revoked player token (all look the same). |
| 403 | key_revoked, key_expired, app_suspended, player_not_allowed | The key, app or player may not use the service. |
| 404 | lobby_not_found, not_found | Also returned for lobbies you may not see. |
| 409 | username_conflict, scoring_not_accepted, lobby_not_open, own_lobby, already_in_lobby, host_has_active_lobby, not_your_turn, stale_version, match_finished, not_matched, and other lobby rules | The action conflicts with the current state. Read the state and decide again. |
| 413 | payload_too_large | Body too big. |
| 429 | rate_limited | Slow down; honour Retry-After. |
| 503 | server_misconfigured, service_not_ready | Temporary service problem. Retry later. |
Rate limits
Limits are per Cloudflare location and approximate, and may change. Current values: session requests 20 per 10 seconds and 120 per minute per client address, 60 per minute per key, 6 per minute per player; lobby reads 60 per minute and lobby changes 20 per minute per player; creating lobbies 3 per minute per player. Poll every few seconds, not faster, and back off when you receive 429.
Testing your integration
- Reproduce the published vectors in your language first.
- With your real credentials, create a player session. Your dashboard shows the first check as passed once DartXchange has recorded it.
- Host a lobby from your app. Pair it with another app: the checks need a different application, so use a second app you registered, or another developer’s. Play a match to a finish.
- Your integration status becomes Integration checks passed only when all four checks are recorded. Revoke every key and the claim is withdrawn.
- Test the failure paths too: a bad signature, a reused nonce, an expired token,
409 stale_version, and a429.
There is no separate sandbox yet: DartXchange offers one environment per access you are given, and test and live use different secrets that do not work in each other’s place.
Browsers and CORS
Session creation is server to server only. Your players’ browsers may call the lobby and match endpoints directly with their player token, but a browser can only do that from an origin DartXchange has allowed. Allowed origins are configured by DartXchange for each app on request; it is not self-service yet. Until your origin is added, make those calls from your own server instead.
Developer Centre · How joining works · Partner Programme
