Authentication · Lydira API

The header

Every authenticated call carries the key as a bearer token. There is no OAuth flow, no refresh token and no session: the key is the whole credential. It is created in Settings → API keys and shown exactly once, so store it before you close the dialog.

Authorization: Bearer sek_0b9a4d182c0f6b9a…

Scope decides which doors open

A scope is checked before the controller runs, and the default is deny: a key that is not full reaches only the endpoints its scope names, and nothing else. This is the difference that matters when a key sits on a PC in an agency office.

full

Reaches

Every endpoint in this reference.

ticket_import

Reaches

/api/v1/ticket_imports

import

Reaches

/api/v1/imports
/api/v1/imports/entities
/api/v1/imports/entities/{key}
/api/v1/imports/{entity}
/api/v1/imports/{entity}/records
/api/v1/imports/{entity}/records/{external_id}
/api/v1/imports/{entity}/validate
/api/v1/imports/{id}
/api/v1/imports/{id}/rows
/api/v1/workspace

A role decides what you may do once inside

Scope and role answer different questions. The agency may additionally bind a key to one of its own roles, and then that role's permission set applies: an operation the role does not cover answers 403 forbidden, and money or personal-data fields the role cannot see come back as null rather than being withheld. A key with no role bound acts with the account owner's unrestricted permissions.

Three more ways a key can be narrowed

IP allowlist: Bind the key to the addresses it should call from. A call from anywhere else answers 403 ip_not_allowed: the credential is fine, so retrying with another token is the wrong move.
Expiry: Give the key an end date. Past it, every call answers 401 key_expired and names the date.
Revocation: Switch a key off without deleting the record, so the name and the usage history survive the incident. Calls answer 401 key_revoked.

Rotation

Issuing a successor does not cut the old key off immediately. It keeps working for 48 hours, which is long enough to deploy the new value in business hours and short enough that "we rotated last week" means the old one is genuinely gone.

The plan gate sits above all of this

API access is a plan feature. On an account whose plan does not include it, every authenticated call answers 403 plan_upgrade_required regardless of scope or role. It is checked before the scope, so that is the error you see first.