API keys

Every call to the API needs a key. The exceptions are /v1/openapi.json, addresses that don't exist, and Lighthouse endpoints Beacon doesn't provide. Each key belongs to your company and carries three choices: what it may do, which runs it can see, and where it may be used from.

In short

An API key is the password your code uses to talk to Beacon. A company owner or admin creates it in the app and chooses what it may do, which runs it can see and where it may be used from. Everyone else only needs to know where to keep it safe.

Keys are created for your company's account, by its owner or an admin. Today, every key comes from Beacon Pro, and one key works on both the Rate Capture API and the Lighthouse-compatible API.

Beacon Pro keys

To create a key:

  1. Sign in to Beacon Pro as the company owner or an admin.
  2. Open your initials in the top right, choose Company, then the API tab.
  3. Under Create a key, give it a name that says where it will be used, such as the system or server that will hold it.
  4. Choose its scope and visibility, and if you like, the IP addresses it may be used from.
  5. Under Expires, choose when the key stops working: never, or after 1, 7, 30 or 90 days. See expiry.
  6. Select Create key and copy the key straight away.
A key is shown once

Beacon stores only a fingerprint of the key, so it can't show it to you again. If you lose one, revoke it and create another. Keep keys in a secrets store or environment variable, and never in code that runs in a browser.

A key looks like bp_k3x9q2m7_ followed by 40 more characters. The first part is its prefix, which is how the key table in the app tells your keys apart. The table also shows when each key was last used.

Send it with every request

Put the key in the Authorization header:

Authorization: Bearer bp_k3x9q2m7_4f8a1c0e9b2d7f6a3c5e8b1d0f9a2c4e6b8d1f3a

Lighthouse clients already send their token in a header called X-Oi-Authorization. Beacon accepts that header too, on both APIs, so you only need to change the token and the base URL. If a request sends both, the Authorization: Bearer header wins.

Scope: what a key may do

In the app In the API It can
Read read Every GET: credits, reports, runs, rows and rates, plus the whole Lighthouse-compatible API.
Read and write read_write Everything a read key can, plus create reports, start runs (which spends credits), retry failed checks and delete rows.

Give reporting tools, spreadsheets and dashboards a read key with All company runs visibility, so they can see the runs another key starts. Keep read and write keys for the one system that starts runs. A write call made with a read key answers 403 scope_read_only.

Visibility: which Rate Capture runs a key can see

Visibility is about Rate Capture. It decides which reports and runs a key can see, and so which subscriptions it can read through the Lighthouse-compatible API.

In the app In the API It sees
Its own runs (the default) own Only the reports and runs this key created.
All company runs company Every report and run in your company, including those made in the app.

A report or run a key can't see answers 404 not_found, as if it didn't exist, and never appears in a list. Through the Lighthouse-compatible API, a subscription the key can't see answers an empty list with general.missing. No key can ever see another company's reports.

Use Its own runs when several systems share one company account and each should only see its own work. Use All company runs when a tool should pick up reports your team runs in the app.

Allowed IP addresses

You can limit a key to your own servers. Enter IPv4 addresses or ranges, separated by commas, for example 203.0.113.7, 10.0.0.0/8. A range is written as an address, a slash and the number of fixed bits. Leave the box empty to accept any address.

The list is set when the key is created and can't be changed afterwards. A request from anywhere else answers 403 ip_not_allowed. To allow another address, create a new key with it on the list and revoke the old one.

Expiry

A key can be set to expire when it is created: never (the default), or after 1, 7, 30 or 90 days. A key with an expiry stops working at 23:59:59 UTC on its last day, which is that number of days after the UTC date it was created on. So a 7-day key created at any time on 5 October works until 23:59:59 UTC on 12 October. The key table in the app shows the last day.

After that, requests with the key answer 401 key_expired. An expired key is no longer listed in the app, doesn't count towards your company's live keys, and is deleted 90 days after it expired. The expiry can't be changed: create a new key before the old one runs out.

Revoke a key

Select Revoke next to the key in the app. It stops working, and requests with it answer 401 key_revoked. Revoked keys stay listed for reference and are deleted after 90 days.

A key stops working if its creator is deactivated

A key works as the person who created it. If that person leaves and their account is deactivated, the key stops working (401 user_disabled). Before deactivating someone, create replacement keys for the systems that use theirs.

Limits

A company can have up to 50 live keys by default, and each key can make a set number of reads and writes a minute. Beacon can set different limits for your company. Every limit, and what happens when you reach it, is on Limits.

If a request is refused

Beacon checks the key in this order and answers with the first problem it finds:

Problem Answer What to do
No key sent 401 missing_token Add the Authorization header.
Too many unknown keys from your address 429 rate_limited Wait an hour, then check the key you are sending.
Key not recognised 401 invalid_token Check for a typo or a missing part of the key.
Key revoked 401 key_revoked Create a new key.
Key expired 401 key_expired Create a new key.
Key's user or company not active 401 user_disabled If the person was deactivated, create a key as an active owner or admin. If the company was deactivated, email support@getbeacon.cloud.
Request from an address not on the list 403 ip_not_allowed Send it from an allowed address, or create a new key that allows this one.
Write call with a read key 403 scope_read_only Use a read and write key.
Over the key's per-minute limit 429 rate_limited Wait for the seconds in Retry-After.

Every other error is listed on the Errors page.