BOUW MEE AAN MEER SPEELPLEZIER

Eén account.
Veilig verbonden.

Koppel je spel via OAuth 2.0 Authorization Code met PKCE S256. Spelers geven zelf toestemming en jij ontvangt alleen hun spelnaam en een unieke identiteit voor jouw spel.

1. Registreer je spel

Publiceer een goedgekeurd spel met een actief uitgeversabonnement. Kies in je dashboard Accounts koppelen en registreer één exacte HTTPS-callback op het domein van je spel. Je ontvangt een publieke client-ID; er is geen client-secret nodig. Wildcards en redirects naar een andere host zijn niet toegestaan.

2. Begin de aanmelding

Genereer per poging een cryptografisch willekeurige state en code_verifier van minimaal 43 URL-veilige tekens. Bewaar ze kort, aan de serverzijde, gebonden aan de browser die de aanmelding startte. Bereken code_challenge = BASE64URL(SHA256(code_verifier)).

GET https://vakantiespelletje.nl/o/authorize/
  ?response_type=code
  &client_id=JOUW_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fjouwspel.nl%2Fauth%2Fcallback
  &scope=profile
  &state=WILLEKEURIGE_EENMALIGE_STATE
  &code_challenge=S256_CHALLENGE
  &code_challenge_method=S256

De speler bevestigt zijn e-mailadres, logt in en ziet welk spel toegang vraagt. Er wordt nooit automatisch toestemming verleend.

3. Controleer de callback en wissel de code in

Vergelijk state in constante tijd met de opgeslagen waarde. Verwerp ontbrekende, verlopen of hergebruikte pogingen en callbacks met een OAuth-fout. Gebruik dezelfde exacte callback-URL bij de uitwisseling. De code is maximaal 60 seconden geldig en maar eenmaal bruikbaar.

POST https://vakantiespelletje.nl/o/token/
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=JOUW_CLIENT_ID
&redirect_uri=https%3A%2F%2Fjouwspel.nl%2Fauth%2Fcallback
&code=ONTVANGEN_CODE
&code_verifier=OPGESLAGEN_VERIFIER

Bij succes ontvang je een bearer access_token met expires_in: 300. Er worden geen refresh-tokens verstrekt. Gebruik het token direct voor het identiteitsverzoek en verwijder het daarna. Geef je eigen spel een afzonderlijke veilige sessie.

4. Haal de identiteit op

GET https://vakantiespelletje.nl/api/v1/me/
Authorization: Bearer TOEGANGSTOKEN

{
  "sub": "een-stabiele-spelspecifieke-identiteit",
  "username": "gekozen-spelnaam",
  "issuer": "https://vakantiespelletje.nl"
}

Koppel op de combinatie issuer + sub. Het sub-nummer verschilt per client/spel. E-mail en wachtwoord worden niet gedeeld. De spelnaam kan veranderen en is geen veilige accountsleutel. Controleer de verwachte issuer en vorm van de reactie.

5. Bestaande accounts koppelen

Log een speler eerst in op het bestaande spelaccount, vraag bij een koppeling opnieuw een recente authenticatie en bevestiging, en verbind daarna expliciet de externe identiteit. Koppel nooit automatisch op naam of e-mailadres. Een externe identiteit mag maximaal één spelaccount hebben. Een database-unique-constraint voorkomt gelijktijdige dubbele koppelingen.

6. Uitloggen en intrekken

Je spel heeft een eigen uitlogfunctie. Je kunt een platformtoken intrekken via POST /o/revoke_token/ met token en client_id. De speler kan koppelingen en alle platformtokens intrekken in Mijn speelplek. Je lokale spelsessie moet apart verlopen en beveiligd worden; platformintrekking is geen automatische single logout van een reeds uitgegeven lokale sessie.

Endpoints

Fouten en limieten

Een ongeldig/verlopen token geeft 401 invalid_token. Een onbekende client, gewijzigde callback, ongeldige scope of ontbrekende/verkeerde PKCE geeft een OAuth-fout. Misbruiklimieten geven 429 met een wachttijd. Tokenverzoeken moeten via je server gebeuren; CORS wordt niet geopend voor willekeurige websites.

Veiligheidsafspraken

• Gebruik alleen HTTPS en een exacte allowlist van callback-URL's.
• Accepteer alleen PKCE S256; password, implicit en client-credentials grants zijn uitgeschakeld.
• Log geen code, verifier, bearer token, cookie, wachtwoord of authorization header.
• Bewaar client-ID's per spel en combineer accounts niet tussen publishers.
• Respecteer intrekking, bans en je eigen leeftijds-/privacybeleid.
• Gebruik HttpOnly, Secure en passende SameSite-cookies voor je eigen sessie.

De broncode bevat een Node.js-client, OpenAPI-specificatie en beveiligingstests. Lingospelen gebruikt dezelfde backendflow voor expliciet gekoppelde accounts.