Your Beamer API key carries a set of permissions that decide what it is allowed to do. A request that is blocked by a missing permission does not always look like a permissions problem, so this article covers where to set them, what each one gates, and how to read the errors.
Where to find them
Go to Settings > API. Each key lists the permissions enabled for it. Toggle a permission on or off and save. Changes apply to new requests immediately.
Permissions that change what a response contains
Most permissions block a request outright. One does not.
Read posts (ignore filters)
GET /posts with ignoreFilters returns nothing until the key has Read posts (ignore filters) enabled. The request still succeeds. You get a 200 and an empty result set, not an error.
If you are calling /posts with ignoreFilters and getting an empty list back when you know posts exist, check this permission first. An empty successful response is the symptom.
Reading API errors
Response | What it usually means |
|---|---|
200 with an empty result | The request was allowed but a permission is limiting what it can return. See ignoreFilters above, or check the segment filters on the posts you expect. |
401 The API Key is invalid | The key does not exist. Either it was revoked, or the product it belonged to was deleted. |
403 | The key is valid but is not permitted to perform this action. Check the permissions on the key in Settings > API. |
429 | Too many requests. Back off and retry. See Is there any limit for API requests? |
500 | A server-side error. If it is repeatable, send us the request and the time it happened. |
If you see 500 or 429 on a key you believe you revoked, you are probably using a key that still exists. A key belonging to a deleted product returns 401, not 500. Check which product the key belongs to before assuming the revocation failed. This is a common source of confusion for organisations running several Beamer accounts with similar names.
Rotating or revoking a key
Create the new key first, move your integrations onto it, then remove the old one. Removing a key takes effect immediately and any integration still using it starts returning 401 straight away. There is no grace period and no warning.
If you cannot reach Settings > API because you no longer have access to the account, see Requesting account and data deletion for what to send us.
If an API key is exposed
If a key has been shared, committed to a public repository, or leaked in any other way, remove it straight away. Don't wait to move your integrations first.
Go to Settings > API and create a new key.
Remove the exposed key. It stops working immediately, so anything still using it will return 401 until you switch it over.
Move your integrations onto the new key.
If you need to know whether the key was used, open the chat at the bottom-left of your dashboard and type "talk to a person." Send us your Product ID, the last few characters of the exposed key, and roughly when it was exposed.
What we can and can't provide
Last 30 days: we keep detailed API request logs for 30 days.
Older than 30 days: we keep a summary of request counts for your product. We can export this for you.
Per key: the summary isn't split by API key, so for older periods we can't tell you which key made a request.
To limit the damage from a future leak, give each integration its own key, and use a read-only key anywhere it would be visible to others, such as in front-end code.