User Authentication

OAuth2 Flow

Players that use your client must authenticate through an OAuth2 login flow.
The Wizard API Client SDK (Kotlin Multiplatform) provides built-in methods to handle this on both JVM and JavaScript targets.

Step 1: Get login endpoints

To begin the flow, the client fetches the login and token URLs:

GET https://wizard-api.kluster.htiprojects.nl/api/client/auth-urls
X-Wizard-Client-Type: <your-client-id>

Response:

{
  "authUrl": "string",
  "tokenUrl": "string"
}

Step 2: Redirect to login

Redirect the user to the authUrl with a code challenge and redirect URI.
You must generate a code_challenge using SHA256 and store the corresponding code_verifier to use later.

GET {authUrl}
  ?client_id=wizard-api
  &response_type=code
  &scope=openid
  &code_challenge=3zX4hA7...7JdT
  &code_challenge_method=S256
  &redirect_uri=https://yourgame.com/oauth/callback
  &state=xyz123

Step 3: Exchange authorization code for tokens

After the user logs in, they are redirected to your redirect_uri with a code query parameter.
Exchange this code for a JWT using the tokenUrl endpoint:

POST {tokenUrl}
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
client_id=wizard-api&
code=abc123xyz&
code_verifier=U6pYc7gK...gZTms&
redirect_uri=https://yourgame.com/oauth/callback

Step 4: Use the access token

On success, the response includes tokens you can use to authenticate API calls.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "expires_in": 3600,
  "refresh_expires_in": 86400,
  "refresh_token": "8xLOxBtZp8",
  "token_type": "Bearer",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "session_state": "abc-def-ghi",
  "scope": "openid"
}

The access_token authenticates the user, and all in-game actions (like playing cards) are performed in their name.
You can inspect the decoded access_token to retrieve user information:

• sub – unique user ID (called the wizardId)
• preferred_username – the player’s display name

The access token must be included in the Authorization header on all further requests towards the API.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...