Skip to content

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.

Create a key in the dashboard. In the sidebar, select Organization settings. In the settings menu, 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.

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 selectedScope
Nonenone
Read<resource>:read
Read and Write<resource>:write

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

ResourceEndpoints
matches/v1/matches, /v2/matches, facts, lineups and match summaries
competitions/v1/competitions, competition images and /v2/competitions/{competitionId}/theme-profiles
teams/v1/teams, team rosters, adding players to a team and team images
players/v1/players, /v1/officials and player images
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, Rive graphics, /v2/control-rooms, /v2/game-plans, /v2/schemas, /v2/scenarios
images/v1/image-templates and their default images
media/v1/media/images, the organization’s media library

The resource is the first path segment after the version, with four exceptions. /v1/officials uses players, /v1/image-templates uses images, and /v2/control-rooms and /v2/game-plans use themes. read allows every GET on the resource. write allows every request on the resource.

No endpoint requires data-sources:read yet. The dashboard disables this box. 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. The key’s organization must also have API access through an active product. This check is not enforced yet: a valid key works whatever the organization’s products. Once it is enforced, a key whose organization lacks API access gets 403 with code: "API_ACCESS_REQUIRED", even when it has the route scope.

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

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.

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 still needs organization-level API access. You cannot create a new one.

Move each integration to a scoped key, then delete the legacy 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.

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.

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.

StatusWhenBody
401The key is missing or unknown, the Authorization format is invalid, or the headers contain different keys{ "message": "…", "code": "UNAUTHENTICATED" }
401The key has expired{ "message": "…", "code": "API_KEY_EXPIRED" }
403The key is valid but lacks the scope for the route{ "message": "…", "code": "INSUFFICIENT_SCOPE" }
403The key’s organization lacks API access (not enforced yet){ "message": "This organization does not have API access", "code": "API_ACCESS_REQUIRED" }
403The resource belongs to another organization, on most routes{ "message": "…", "code": "FORBIDDEN" }
404The resource does not exist, or a theme belongs to another organization{ "message": "…" }
429The organization of the key has used its rate limit and enforcement is on{ "message": "Organization has made too many requests" }
429The request has no valid key, its client IP address has used its rate limit, and enforcement is on{ "message": "Client IP address has made too many requests" }

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