Authentication

Every REST request carries an API key in a header. A key belongs to one organization. A key has one or more scopes, and an optional expiry date.

API keys

Create a key in the dashboard. Open the account menu at the bottom of the sidebar and select Developers. On the API keys tab, select Create API key. Pick the access for each resource, pick an expiry, and select Create key. LIGR shows the full key once. After that it shows only the first four and the last four characters.

Only an organization admin or owner sees Developers. If the menu does not show it, ask an admin or owner to create the key.

A key starts with ligr_. LIGR stores only a hash of the key. If you lose a key, create a new one.

Note

Treat a key like a password. Keep it in a secrets store. Never put it in a browser or a shared spreadsheet.

Scopes

A scope is <resource>:read or <resource>:write. write on a resource includes read on that resource.

The dashboard groups resources by product area. Each resource has a Read box and a Write box. Select Write to also select Read. A group header box sets every resource in that group. The key list shows the scopes of each key.

Boxes selected	Scope
None	none
Read	<resource>:read
Read and Write	<resource>:write

Each endpoint in the REST reference names the scope it needs.

Resource	Endpoints
matches	/v1/matches, /v2/matches, facts, lineups and match summaries
competitions	/v1/competitions
teams	/v1/teams, team rosters and adding players to a team
players	/v1/players, /v1/officials
venues	/v1/venues
overlays	/v1/overlays, /v2/overlays, graphics commands and control room graphics
streams	/v1/streams, go-live, overlay show and hide
data-sources	/v2/data-sources
themes	/v2/themes, code graphics, /v2/schemas, /v2/scenarios

The resource is the first path segment after the version, except /v1/officials, which uses players. read allows every GET under that segment. write allows every request under that segment.

No endpoint requires players:write or data-sources:read yet. The dashboard disables these two boxes. To create a player, use POST /v1/teams/{teamId}/players with teams:write.

A key that lacks the scope for a route returns 403 with code: "INSUFFICIENT_SCOPE". The message names the missing scope. LIGR checks the scopes of the key, not the role of the user who created it.

Grant the smallest set of scopes that works. A score feed needs matches:write. A results website needs matches:read and competitions:read.

Expiry

Pick an expiry when you create the key: 7, 30, 60, 90 days, one year, or a custom date. The default is 30 days. An expired key returns 401 with code: "API_KEY_EXPIRED". Create a new key before the old one expires. See Rotate a key.

You can also choose No expiration. The dashboard warns you first. A key with no expiry stays valid until you delete it. Choose it only when the integration cannot rotate keys.

Legacy keys

Keys created before scopes existed are legacy keys. The dashboard labels them Legacy.

• A legacy read key has read on every resource.
• A legacy write key has write on every resource.
• A legacy key never expires.
• A legacy key keeps working. You cannot create a new one.

Move each integration to a scoped key, then delete the legacy key.

Send the key

Use Authorization: Bearer <api key> for new integrations. Both scoped and legacy keys work with this header.

Terminal

curl https://api.ligr.live/rest/v1/competitions \
  -H 'Authorization: Bearer YOUR_API_KEY'

Existing integrations can keep using the legacy x-ligr-api-key header:

x-ligr-api-key: YOUR_API_KEY

Both headers use the same key validation, scopes, and expiry checks. Changing the header does not require a new key.

Send one authentication header per request. If both headers are present, they must contain the same key. Different keys return 401. An invalid Authorization format also returns 401, even when x-ligr-api-key contains a valid key.

REST routes ignore keys in the query string.

Caution

Send an API key as the Bearer token. REST routes do not accept dashboard or overlay JWTs.

Who can create keys

Organization owners and admins can create and delete a key.

A key acts for the whole organization, within its scopes. It sees every competition and match that the organization owns, and nothing else.

A request for a resource in another organization is always refused. The status is not uniform today: theme routes return 404, and match, team, player, overlay, stream and data source routes return 403. Do not read ownership from the status code.

Rotate a key

There is no REST endpoint for keys today. Follow these steps.

1. Create the new key in the dashboard with the same scopes.
2. Deploy the new key to your service.
3. Delete the old key in the dashboard.

Both keys work during the overlap. Deletion takes effect at once.

Errors

Status	When	Body
401	The key is missing or unknown, the Authorization format is invalid, or the headers contain different keys	{ "message": "…", "code": "UNAUTHENTICATED" }
401	The key has expired	{ "message": "…", "code": "API_KEY_EXPIRED" }
403	The key is valid but lacks the scope for the route	{ "message": "…", "code": "INSUFFICIENT_SCOPE" }
403	The resource belongs to another organization, on most routes	{ "message": "…", "code": "FORBIDDEN" }
404	The resource does not exist, or a theme belongs to another organization	{ "message": "Not Found" }
429	The rate limit is exceeded and enforcement is on	{ "message": "Api key has made too many requests" }

See Errors for the full status map. See Rate limits for the headers and the 429 response.