Authentication and headers¶

During the Beta test phase, direct REST integrations use API key authentication. Keys are issued by the bsport team and grant access to act on behalf of your company or franchise team within the scope they were created for.

Connections from compatible AI assistants use OAuth instead of an API key. See Connect an AI assistant with MCP. The remainder of this page applies only to direct REST integrations.

Keep your API key secure

Treat your API key like a password. Store it server-side, alert the bsport team if it is exposed, and never embed it in client-side code.

REST API key header¶

Send your API key in the X-Api-Key header on every request.

curl -X GET \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Client-ID: YOUR_CLIENT_ID' \
  -H 'X-Company-ID: YOUR_COMPANY_ID' \
  'https://YOUR_ENV_DOMAIN/api/v2/management/clients/'

Replace YOUR_ENV_DOMAIN with public.staging.bsport.io (staging) or public.production.bsport.io (production). See Environments.

Tenant and client headers¶

Every request must include headers that identify the calling client and the tenant (company or franchisor) you are operating on.

Required headers¶

X-Api-Key: authenticates the request.
X-Client-ID: identifies your integration for tracing and support.
X-Company-ID or X-Franchisor-ID: sets the tenant context.

Tenant context rules¶

Company API keys must include X-Company-ID.
Franchise API keys must include X-Franchisor-ID.
Franchise API keys can optionally include X-Company-ID to act on behalf of a specific company within that franchise.

Company API keyFranchise API key

X-Api-Key: YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID
X-Company-ID: YOUR_COMPANY_ID

X-Api-Key: YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID
X-Franchisor-ID: YOUR_FRANCHISOR_ID
X-Company-ID: TARGET_COMPANY_ID

Optional headers¶

X-Timezone-Name: replaces the target company's time zone for a V2 GET request. See Dates, time zones and amounts.

X-Timezone-Name: Europe/Paris

Consistent client IDs help support

Keep your X-Client-ID stable across environments so we can trace requests quickly during troubleshooting.

Check your API key and usage¶

Send GET /api/v2/monitoring/me/ with your usual headers to see which key you are using and how many calls were made on its company or franchise. The response gives the key's client_id, its company or franchise, expires_at, and the successful calls (2xx or 3xx) of the last 12 UTC calendar months, current month first. Counts cover the whole company or franchise, not one key. A month without calls shows 0.

The current month is live. Earlier months are copied once a day, at 02:15 Paris time: until that copy on the 1st, the previous month misses up to its last day of calls.

What the counts cover depends on the key:

Key	`monthly_usage`	`companies`
Company API key	Every call made on your company	Empty
Franchise API key	Every call made with your franchise's keys	Each company of the franchise, with every call made on it

Company counts include franchise-key calls only from the release that added this endpoint, so earlier months of a franchise company show fewer calls. See the Changelog.

X-Company-ID does not change the answer for a franchise key. This call counts like any other and follows the default rate limits.

REST API key troubleshooting¶

If you receive a 401 or 403, confirm that your API key is valid and that you are sending the required tenant headers. See Tenant and client headers for details.