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`,
{
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;
}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.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;
}Perform all token exchanges on your server, not in browser or mobile code.
Authentication errors
| Status | Error code | Resolution |
|---|---|---|
401 | invalid_api_key | Check the key is correct and not revoked |
401 | expired_token | Refresh the access token |
401 | missing_credentials | Include X-API-Key or Authorization header |
403 | insufficient_scope | See Scopes |