Lumirank Authentication
How to send your API key, what read and write keys can do, which plans include the API, and what to do if a key leaks.
Send the key with every request
Put the key in the Authorization header of every request:
Authorization: Bearer lr_7Hk2pQ9xWm4vRt8nYb3cLs6dFj1aZe5uGo0iKw2NA key is lr_ followed by 40 letters and digits. Never put a key in a URL or a query string, because proxies and servers write URLs to their logs.
The API does not allow calls from a web page in a browser: it sends no CORS headers. Call it from a server, a script, or a BI tool. Do not put a key in code that runs in a browser, because anyone who opens the page can read it.
Each key works for 1 brand
A key reads and changes the data of 1 brand only. To work with 2 brands, create a key for each of them. GET /v1/brand returns the brand and the key that a request used.
Read keys and write keys
| Access | What the key can call |
|---|---|
| Read | Every GET request: the brand, prompts, competitors, answers, mentions, citations, and the 3 reports. |
| Read & write | Everything a read key can call, plus POST /v1/prompts, PATCH /v1/prompts/{prompt_id}, and PATCH /v1/competitors/{competitor_id}. |
If a read key calls a write endpoint, it gets status 403 with the error code insufficient_permission. No key can delete data or start a run.
Plans that include the API
The Starter, Pro, and Scale plans include API access, and so does the trial. On the Free plan, every request gets status 403 with the error code plan_upgrade_required. Your keys stay saved, and they work again after you upgrade.
Who can manage keys
Owners and managers of the organization create, edit, and revoke keys in Settings > API keys. Members cannot see the keys. A key keeps working after the person who created it leaves the organization.
A brand can have up to 10 active keys. For each key, the page shows its name, its first and last characters, its access, who created it, and when it was last used.
Replace a key with a new one
- Create a new key with the same access.
- Put the new key in your app or your secret store, and deploy it.
- Revoke the old key.
If a key leaks
Revoke it at once in Settings > API keys. The next request with that key gets status 401 with the error code api_key_invalid. Then create a new key for your app. A change of access, for example from read and write to read only, also takes effect from the next request.