Welk API-token moet je game gebruiken?

Game Stats AI heeft twee soorten API-tokens. Een client-token kan telemetrie versturen, zoals matches en achievement-events, maar kan geen rapporten lezen. Een server-token kan telemetrie versturen en rapporten lezen. Gebruik een client-token in alles wat in een build van je game wordt meegeleverd, en een servertoken in code die draait op een machine die jij beheert.

Wat elk token kan

Kies het type wanneer je het token aanmaakt bij Instellingen > API-tokens. Het volledige token wordt één keer getoond, direct nadat je het hebt aangemaakt. Nieuwe tokens beginnen met hun type, client_ of server_, zodat je kunt zien welk soort token in je code staat.

Wat de API voor elk token teruggeeft

De verzoeken hieronder zetten je account-id en beide tokens in omgevingsvariabelen:

export ACCOUNT_ID=your_account_id
export CLIENT_TOKEN=client_your_token
export SERVER_TOKEN=server_your_token

Elk verzoek gebruikt -w "\n%{http_code}\n", dat de HTTP-statuscode na de body van het antwoord toont.

Een client-token kan telemetrie versturen

Verstuur een match naar het matches-endpoint met het client-token:

curl -s -w "\n%{http_code}\n" -X POST "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/matches" \
  -H "Authorization: Bearer $CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "match_8f3a2c", "version_name": "2.1.0", "match_at": "2026-10-12T20:15:00Z", "match_players": [{"username": "player_3e8", "match_attributes": {"win": 1, "loss": 0}}, {"username": "player_40d", "match_attributes": {"win": 0, "loss": 1}}]}'

{}
201

201 Created betekent dat de match is geaccepteerd. De endpoints voor achievement-events, progressie-events, personages en achievements accepteren een client-token op dezelfde manier.

Een client-token kan geen rapporten lezen

Vraag de rapporten van het account op bij het endpoint voor personagerapporten met hetzelfde token:

curl -s -w "\n%{http_code}\n" "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/character_reports" \
  -H "Authorization: Bearer $CLIENT_TOKEN"

403

403 Forbidden betekent dat het token geldig is, maar dat het type van het token dit verzoek niet mag doen. De body is leeg, dus toon de statuscode om dit te zien. Elk endpoint dat gegevens leest, antwoordt zo op een client-token, en de MCP-server ook.

Een token dat niet bestaat, of dat is ingetrokken, krijgt in plaats daarvan 401 Unauthorized.

Een servertoken kan rapporten lezen

Verstuur hetzelfde verzoek met het servertoken:

curl -s -w "\n%{http_code}\n" "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/character_reports" \
  -H "Authorization: Bearer $SERVER_TOKEN"

[{"id":1,"external_id":null,"label":"Character Win Rates","description":null}]
200

200 OK betekent dat het verzoek is gelukt, en de body bevat de lijst met personagerapporten van het account. Een servertoken kan ook alles versturen wat een client-token kan versturen.

Welk token je waar gebruikt

• In een build van je game, voor desktop, mobiel, console of browser: gebruik een client-token. Spelers downloaden de build, en iedereen die zoekt, kan het token erin vinden.
• Op je gameserver of backend: gebruik een servertoken. Als je game resultaten al via een backend van jezelf verstuurt, verstuur de telemetrie dan vanaf die backend, en er gaat geen enkel token naar spelers.
• In je eigen scripts en in de MCP-server: gebruik een servertoken en houd het op je eigen computer.

Behandel elk token in een build van je game als openbaar. Een client-token beperkt wat iemand die het vindt kan doen: die persoon kan telemetrie naar je account versturen, maar kan je rapporten en andere gegevens in je account niet lezen.

Wat browseroorsprongen wel en niet doen

Voor een browsergame moet je ook de origin toevoegen bij Instellingen > Browseroorsprongen. De Phaser-handleiding laat zien hoe.

Voordat een pagina een verzoek met een token naar een ander domein verstuurt, vraagt de browser aan dat domein of de origin van de pagina is toegestaan. Dit verzoek heet een preflight. Je kunt dezelfde preflight met curl versturen:

curl -s -i -X OPTIONS "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/matches" \
  -H "Origin: https://play.yourgame.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: authorization, content-type"

Voor een origin die je hebt toegevoegd, bevat het antwoord deze header:

access-control-allow-origin: https://play.yourgame.com

Voor een origin die je niet hebt toegevoegd, ontbreekt de header, en verstuurt de browser het verzoek niet.

De browser voert deze controle uit, niet de API. curl, scripts en games die niet in een browser draaien, slaan de preflight over en versturen het verzoek direct. Hier verstuurt het client-token een match met een origin die niet in de lijst staat:

curl -s -w "\n%{http_code}\n" -X POST "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/matches" \
  -H "Origin: https://not-your-game.example" \
  -H "Authorization: Bearer $CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "match_8f3a2d", "version_name": "2.1.0", "match_at": "2026-10-12T20:20:00Z", "match_players": [{"username": "player_3e8", "match_attributes": {"win": 0, "loss": 1}}, {"username": "player_40d", "match_attributes": {"win": 1, "loss": 0}}]}'

{}
201

De match is geaccepteerd. Browseroorsprongen voorkomen dat andere websites je token gebruiken in de browser van hun bezoekers. Ze beperken niet wat een token buiten een browser kan doen, dus ze beschermen een gelekt token niet. Dat doet het type van het token. Games die niet in een browser draaien, hebben geen origins nodig.

Als een token lekt

Trek het in bij Instellingen > API-tokens. Elk verzoek met een ingetrokken token krijgt vanaf dat moment 401, ook verzoeken uit builds die je spelers al hebben.

Een gelekt servertoken kan alle gegevens van je account lezen, dus trek het meteen in en maak een nieuw token aan.

Een gelekt client-token kan alleen telemetrie versturen, dus je kunt kiezen wanneer je het intrekt. Trek het meteen in om de verzoeken te stoppen, of publiceer eerst een update met een nieuw client-token zodat huidige spelers events blijven versturen, en trek daarna het oude token in.