Developer Centre · API reference

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.

Status. The API is not public yet and developer registration is not open. There is no public API address on this page: once you have an approved app, your dashboard shows the address to use. Names such as dxk_ExampleKeyId0001 below are placeholders, never real credentials. Anything not described here (friends, invitations, spectators, video) does not exist.

Steps to integrate

  1. Register a developer account, verify your email and wait for DartXchange to approve it.
  2. 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.
  3. 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).
  4. Sign your server’s requests (section below) and create a player session when one of your players wants to play across apps.
  5. Use the lobby and match endpoints with the short-lived player token.
  6. 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.
  7. 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:

HeaderValue
X-DX-Key-IdYour key id: dxk_ + 16 characters
X-DX-TimestampUnix time in seconds (10 digits), within 300 seconds of DartXchange’s clock
X-DX-Nonce16–64 characters of A-Za-z0-9_-, new for every request (a repeat is 401 replayed_request)
X-DX-Signaturebase64url(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_method is 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-sessions with Authorization: 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.

CallWhat it does
POST /v1/lobbiesHost 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=20Open 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}/requestsAsk to join. A lobby whose scoring requirement you do not meet is refused with 409 scoring_not_accepted.
DELETE /v1/lobbies/{id}/requestsWithdraw a request, or leave after being accepted.
POST /v1/lobbies/{id}/requests/{player_id}/accept · .../rejectThe host answers a request. Both players then see the pairing.
POST /v1/lobbies/{id}/heartbeatHost keeps an open lobby alive (5 minutes at a time, up to 30 minutes of waiting).
POST /v1/lobbies/{id}/cancel · /closeThe host cancels an open lobby; host or guest ends a matched game.
GET /v1/me/lobbyYour 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 }
  • score is the visit total, 0–180. expected_version is the version you last read: a retry or double click is refused with 409 stale_version instead 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) are 400 invalid_checkout.
  • 409 not_your_turn, 409 match_finished and 409 not_matched are 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.

StatusCodesMeaning
400invalid_json, invalid_content_type, unknown_field, invalid_username, invalid_external_player_id, invalid_scoring_method, invalid_query, invalid_checkoutThe request is not acceptable. Only documented fields are allowed.
401signing codes above, invalid_tokenSigning problem, or a bad, expired or revoked player token (all look the same).
403key_revoked, key_expired, app_suspended, player_not_allowedThe key, app or player may not use the service.
404lobby_not_found, not_foundAlso returned for lobbies you may not see.
409username_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 rulesThe action conflicts with the current state. Read the state and decide again.
413payload_too_largeBody too big.
429rate_limitedSlow down; honour Retry-After.
503server_misconfigured, service_not_readyTemporary 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

  1. Reproduce the published vectors in your language first.
  2. With your real credentials, create a player session. Your dashboard shows the first check as passed once DartXchange has recorded it.
  3. 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.
  4. Your integration status becomes Integration checks passed only when all four checks are recorded. Revoke every key and the claim is withdrawn.
  5. Test the failure paths too: a bad signature, a reused nonce, an expired token, 409 stale_version, and a 429.

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