OAuth 2

TournamentSuite uses OAuth 2 for user-scoped authentication. Access tokens are short-lived JWTs issued by the TournamentSuite identity provider. They must be included in every request that requires a specific user context.

Grant types

TournamentSuite supports two OAuth 2 grant types.

Client Credentials (machine-to-machine)

Use this when your server needs to call the API on its own behalf — not on behalf of a specific user. This is the most common pattern for backend integrations.

curl -X POST "$OIDC_ISSUER/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=read:tournaments manage:matches"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "expires_in": 900,
  "token_type": "Bearer",
  "scope": "read:tournaments manage:matches"
}

Authorization Code (on behalf of a user)

Use this when a user grants your application permission to act on their account — for example, registering them in a tournament.

1. Redirect the user to the authorization endpoint:

GET $OIDC_ISSUER/protocol/openid-connect/auth
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=openid read:tournaments

2. The user authenticates and is redirected back to your redirect_uri with a code parameter.

3. Exchange the code for tokens:

const tokenResponse = await fetch(
  `${process.env.OIDC_ISSUER}/protocol/openid-connect/token`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded'

Token lifecycle

When the access token expires, use the refresh token to get a new one without requiring the user to log in again:

async function refresh(refreshToken: string) {
  const response = await fetch(
    `${process.env.OIDC_ISSUER}/protocol/openid-connect/token`,
    {

Discovery document

Your OAuth 2 client endpoint URLs can be discovered programmatically:

GET $OIDC_ISSUER/.well-known/openid-configuration

This returns the token endpoint, authorization endpoint, and supported scopes for your TournamentSuite environment.

Security recommendations

• Store access tokens in server-side session storage, not in localStorage or cookies accessible to JavaScript.
• Treat refresh tokens like passwords — store them encrypted and rotate them regularly.
• Use PKCE (Proof Key for Code Exchange) when implementing the Authorization Code flow in a browser or mobile app.
• Always validate the token's iss, aud, and exp claims before accepting it in your own services.