TS
Tournament Suite
TS
Tournament Suite
Developer Documentation
AuthenticationAuthorizationScopesOAuth 2
Security

Authentication

How to authenticate requests to the TournamentSuite API using API keys or OAuth 2 access tokens.

The TournamentSuite API supports two authentication methods depending on your integration type.

API key authentication (recommended for server-side)

API keys are the simplest way to authenticate server-to-server requests. Include your key in the X-API-Key header on every request.

curl https://api.tournamentsuite.com/api/v1/tournaments \
  -H "X-API-Key: YOUR_API_KEY"
const apiClient = axios.create({
  baseURL: 'https://api.tournamentsuite.com/api/v1',
  headers: { 'X-API-Key': process.env.TOURNAMENTSUITE_API_KEY },
});

API keys are generated in your project's Settings → Developer → API Keys. Each key is shown only once — store it securely in an environment variable or secrets manager.

Never embed API keys in client-side code, mobile app bundles, or public repositories.

OAuth 2 access tokens (user-scoped requests)

For operations that act on behalf of a specific user — such as a player registering for a tournament — use OAuth 2 access tokens. TournamentSuite's identity layer issues short-lived JWT access tokens via the Authorization Code or Client Credentials grants.

Pass the token in the Authorization header:

curl https://api.tournamentsuite.com/api/v1/users/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

Client Credentials grant (machine-to-machine)

Use this grant when your server needs to act as a system actor rather than as a specific user:

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

Token refresh

Access tokens expire (typically after 15 minutes). Use your refresh token to obtain a new one without requiring the user to re-authenticate:

async function refreshAccessToken(refreshToken: string): Promise<string> {
  const response = await fetch(
    `${process.env.

Perform all token exchanges on your server, not in browser or mobile code.

Authentication errors

StatusError codeResolution
401invalid_api_keyCheck the key is correct and not revoked
401expired_tokenRefresh the access token
401missing_credentialsInclude X-API-Key or Authorization header
403insufficient_scopeSee Scopes

Next steps

  • Authorization & Scopes
  • OAuth 2 Flow

Webhooks

Register endpoints to receive real-time event notifications from TournamentSuite.

Authorization

How TournamentSuite controls access to resources through projects, scopes, and roles.

On this page

API key authentication (recommended for server-side)OAuth 2 access tokens (user-scoped requests)Client Credentials grant (machine-to-machine)Token refreshAuthentication errorsNext steps
{
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'client_credentials',
client_id: process.env.TOURNAMENTSUITE_CLIENT_ID!,
client_secret: process.env.TOURNAMENTSUITE_CLIENT_SECRET!,
scope: 'read:tournaments manage:tournaments',
}),
}
);
const { access_token } = await response.json();
return access_token;
}
OIDC_ISSUER
}/protocol/openid-connect/token`
,
{
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'refresh_token',
client_id: process.env.TOURNAMENTSUITE_CLIENT_ID!,
refresh_token: refreshToken,
}),
}
);
const { access_token } = await response.json();
return access_token;
}