Authentication and API keys.
Every request to the Liberty91 API carries an API key. Keys are created by an account Owner or Admin in the platform, under Account then API Keys (platform.liberty91.com/account/api-keys), and each key belongs to exactly one billing account.
Sending your key
Two header forms are accepted, so you can use whichever your tooling prefers:
# Option 1: dedicated header
curl "https://api.liberty91.com/api/v1/iocs/" \
-H "X-API-Key: l91_live_xxxxxxxxxxxxxxxxxxxxxxxx"
# Option 2: standard bearer token
curl "https://api.liberty91.com/api/v1/iocs/" \
-H "Authorization: Bearer l91_live_xxxxxxxxxxxxxxxxxxxxxxxx"Never put the key in a query parameter, and never ship it to a browser. This is a server-to-server API by design.
Key types
| Prefix | Use |
|---|---|
l91_live_ | Production keys |
l91_test_ | Non-production keys for development and staging |
Key lifecycle
A few properties to know before you build:
- The full secret is shown once, at creation. Afterwards the platform only stores and displays a prefix and the last four characters.
- Lost keys are rotated, not recovered. Create a new one, switch your integration, then revoke the old one.
- Revocation takes effect within about 30 seconds.
Treat API keys like any other production credential: keep them in a secrets manager, give each integration its own key, and grant only the scopes that integration needs. Separate keys also give you clean per-integration rate limit and credit visibility.
Scopes
A key carries a set of scopes that controls what it can call. An empty scope list grants all read scopes. Write scopes must always be granted explicitly.
| Scope | Grants |
|---|---|
threat-events.read | Threat Events, their sources, IOCs and STIX bundles |
threats.read | The threat library: actors, malware, vulnerabilities, clusters |
search.read | Search, and reading or running saved searches |
events.read | Individual reports: list and detail |
iocs.read | IOC lookup, list and export, and every per-entity or per-occurrence IOC and STIX endpoint |
reports.read | Intelligence packages: list, detail, download |
alerts.read | Alert rules and their matches |
orgs.read | Customer organizations, assets, suppliers, documents |
events.write | Ingest your own reports |
reports.generate | Generate intelligence packages |
orgs.write | Upload documents, confirm entities, trigger description refreshes |
Endpoints that need more than one scope
Some endpoints require several scopes, and a key must carry all of them. The rule
is simple: an endpoint requires the scope for every resource whose data it
returns, not only the one it lives under. A sub-resource that serves indicator
data needs iocs.read even though it sits under a Threat Event.
| Endpoint | Scopes |
|---|---|
IOC and STIX sub-resources under /threat-events/ and /threat-library/ | the parent scope and iocs.read |
/threat-library/{type}/{id}/threat-events/ | threats.read and threat-events.read |
/threat-library/{type}/{id}/stix/ | threats.read, iocs.read and threat-events.read |
POST /search/ and POST /searches/{id}/run/ | search.read and threat-events.read |
/alerts/{id}/matches/ | alerts.read and threat-events.read, or alerts.read and events.read with ?results=reports |
GET /reports/{id}/download/?type=csv|stix|sigma | reports.read and iocs.read |
Listing and reading saved searches needs only search.read, since those return
criteria rather than results.
Calling an endpoint without the required scope returns 403 Forbidden with a message
naming the missing scope.
The tenant boundary
Every key is bound to a single billing account, and every response is limited to that
account's data. Objects belonging to another tenant simply do not exist as far as your
key is concerned: requesting them returns 404 Not Found, the same as any other
missing object. This is a hard boundary enforced on every endpoint, not a filter you
opt into.
Frequently asked questions
Where do I create a Liberty91 API key?
An account Owner or Admin creates them in the platform under Account, then API Keys, at platform.liberty91.com/account/api-keys. The full secret is shown once at creation, so store it in your secrets manager right away.
What happens if I lose an API key?
Keys cannot be recovered, only rotated. Create a new key, move your integration over, and revoke the old one. Revocation takes effect within about 30 seconds.
What does an API key with no scopes do?
A key with an empty scope list gets all read scopes. Write scopes always have to be granted explicitly, so a default key can read your intelligence but never change anything.