Implement OAuth sign-in

Choose the identity first

Use Account OAuth for an EnderDash dashboard user. Use Game OAuth for a game account proved by an in-game command.

Register an exact redirect URI. Account clients require an EnderDash platform admin. Game clients are managed by organization owners and admins under Game OAuth.

Configure discovery

Account discovery:

curl --fail-with-body 'https://app.enderdash.com/.well-known/openid-configuration'

Game discovery:

curl --fail-with-body 'https://oauth.enderdash.com/.well-known/openid-configuration'

Use the discovered endpoints and expected issuer in your OIDC library. The account issuer includes /api/auth; do not remove that path.

Start authorization

1. Generate and store an unpredictable state value for this browser session.
2. Generate a PKCE verifier and its S256 challenge with your OAuth library.
3. Generate a nonce when requesting an ID token.
4. Send the browser to the discovered authorization endpoint with response_type=code, the registered client_id, exact redirect_uri, requested scopes, and these values.

For Game OAuth, use openid profile. The user must keep the hosted page open, join a server allowed by the client policy, and run the displayed /enderdash login <code> as a player.

For Account OAuth, the user signs in with their dashboard account and reviews the applicable consent request.

Handle the callback and exchange the code

Verify that callback state matches the stored value before using the code. Exchange the code from your backend using the same redirect URI and stored PKCE verifier.

This Game OAuth example uses confidential-client authentication. Supply these variables securely from your backend environment:

curl --fail-with-body   --user "$CLIENT_ID:$CLIENT_SECRET"   --data-urlencode 'grant_type=authorization_code'   --data-urlencode "code=$AUTHORIZATION_CODE"   --data-urlencode "redirect_uri=$REDIRECT_URI"   --data-urlencode "code_verifier=$PKCE_VERIFIER"   'https://oauth.enderdash.com/oauth2/token'

A code is short-lived and single-use. Do not retry a successful exchange with the same code. Keep client secrets and token responses on the backend.

Validate the identity before starting a session

Use your OIDC library to verify the ID token's signature, issuer, audience, expiration, and nonce. Read keys through discovery and allow key rotation.

For Game OAuth, sub identifies the game account in its organization and game context. It is not an EnderDash dashboard user ID. The verifier server reports the game runtime's identity; this is not an independent Microsoft-account login.

If sign-in fails

Check the issuer, exact callback, client registry, verifier policy, code lifetime, and PKCE values. Restart authorization after an expired or consumed code. Demo mode cannot validate real token exchange or in-game proof.

Use the account reference or game reference for supported scopes, claims, and endpoint authentication.