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
Section titled “API keys”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.
Scopes
Section titled “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, 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.
Expiry
Section titled “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
Section titled “Legacy keys”Keys created before scopes existed are legacy keys. The dashboard labels them Legacy.
- A legacy
readkey hasreadon every resource. - A legacy
writekey haswriteon 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.
Send the key
Section titled “Send the key”Use Authorization: Bearer <api key> for new integrations. Both scoped and legacy keys work with this header.
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_KEYBoth 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.
Who can create keys
Section titled “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
Section titled “Rotate a key”There is no REST endpoint for keys today. Follow these steps.
- Create the new key in the dashboard with the same scopes.
- Deploy the new key to your service.
- Delete the old key in the dashboard.
Both keys work during the overlap. Deletion takes effect at once.
Errors
Section titled “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 key’s organization lacks API access (not enforced yet) | { "message": "This organization does not have API access", "code": "API_ACCESS_REQUIRED" } |
| 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": "…" } |
| 429 | The organization of the key has used its rate limit and enforcement is on | { "message": "Organization has made too many requests" } |
| 429 | The 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.