Authentication¶

Generate Nonce¶

PythonJavaScript

import requests
headers = {
  'Accept': 'application/json',
  'leadr-api-key': 'string',
  'authorization': 'string',
  'leadr-client-nonce': 'string'
}

r = requests.get('/v1/client/nonce', headers = headers)

print(r.json())

const headers = {
  'Accept':'application/json',
  'leadr-api-key':'string',
  'authorization':'string',
  'leadr-client-nonce':'string'
};

fetch('/v1/client/nonce',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v1/client/nonce

Generate a fresh nonce for replay protection.

Nonces are single-use tokens with short TTL (60 seconds) that clients must obtain before making mutating requests (POST, PATCH, DELETE). This prevents replay attacks by ensuring each request is fresh and authorized.

Requires identity authentication via access token.

Args: auth: Authenticated client auth context (identity guaranteed non-None) service: NonceService dependency

Returns: NonceResponse with nonce_value and expires_at

Raises: 401: Invalid or missing access token

Example: 1. Client calls GET /client/nonce with Authorization header 2. Server returns nonce_value and expires_at 3. Client includes nonce in leadr-client-nonce header for mutations 4. Server validates and consumes nonce (single-use)

Parameters¶

Name	In	Type	Required	Description
account_id	query	any	false	none
leadr-api-key	header	any	false	none
authorization	header	any	false	none
leadr-client-nonce	header	any	false	none

Example responses

200 Response

{
  "nonce_value": "string",
  "expires_at": "2019-08-24T14:15:22Z"
}

Responses¶

Status	Meaning	Description	Schema
200	OK	Successful Response	NonceResponse
422	Unprocessable Entity	Validation Error	HTTPValidationError

Success

This operation does not require authentication

Start Session¶

PythonJavaScript

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('/v1/client/sessions', headers = headers)

print(r.json())

const inputBody = '{
  "game_id": "string",
  "client_fingerprint": "string",
  "platform": "string",
  "metadata": {},
  "test_mode": false
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('/v1/client/sessions',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /v1/client/sessions

Start a new identity session for a game client.

This endpoint authenticates game clients and provides JWT access tokens. It is idempotent - calling multiple times for the same fingerprint updates the device record and creates a new identity session.

No authentication is required to call this endpoint (it IS the authentication).

Args: session_request: Session start request with game_id and fingerprint identity_service: IdentityService dependency (handles device and identity creation)

Returns: StartSessionResponse with identity info and access tokens

Raises: 404: Game not found 422: Invalid request (missing required fields, invalid UUID format)

Body parameter

{
  "game_id": "string",
  "client_fingerprint": "string",
  "platform": "string",
  "metadata": {},
  "test_mode": false
}

Parameters¶

Name	In	Type	Required	Description
body	body	StartSessionRequest	true	none

Example responses

201 Response

{
  "identity_id": "string",
  "game_id": "string",
  "account_id": "string",
  "kind": "DEVICE",
  "display_name": "string",
  "access_token": "string",
  "refresh_token": "string",
  "expires_in": 0,
  "test_mode": true
}

Responses¶

Status	Meaning	Description	Schema
201	Created	Successful Response	StartSessionResponse
422	Unprocessable Entity	Validation Error	HTTPValidationError

Success

This operation does not require authentication

Refresh Session¶

PythonJavaScript

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('/v1/client/sessions/refresh', headers = headers)

print(r.json())

const inputBody = '{
  "refresh_token": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('/v1/client/sessions/refresh',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /v1/client/sessions/refresh

Refresh an expired access token using a valid refresh token.

This endpoint implements token rotation for security: - Returns new access and refresh tokens - Increments the token version - Invalidates the old refresh token (prevents replay attacks)

No authentication is required (the refresh token itself is the credential).

Args: request: Refresh token request identity_service: IdentityService dependency

Returns: RefreshTokenResponse with new tokens

Raises: 401: Invalid or expired refresh token 422: Invalid request (missing refresh_token)

Body parameter

{
  "refresh_token": "string"
}

Parameters¶

Name	In	Type	Required	Description
body	body	RefreshTokenRequest	true	none

Example responses

200 Response

{
  "access_token": "string",
  "refresh_token": "string",
  "expires_in": 0
}

Responses¶

Status	Meaning	Description	Schema
200	OK	Successful Response	RefreshTokenResponse
422	Unprocessable Entity	Validation Error	HTTPValidationError

Success

This operation does not require authentication