Authentication
Every API request carries a bearer token. For anything automated, that token is an API key.
Create a key
In the dashboard, go to API keys → Create key. Name it after whatever will use it — github-actions, terraform, status-dashboard — because that name is what you will be looking at in six months deciding whether it is safe to revoke.
The secret is shown once. We store only a hash, so it cannot be shown again or recovered — not by you, and not by us. Copy it straight into your secret store. If it is lost, revoke the key and make another.
Choose the least access it needs
| Field | Type | Notes |
|---|---|---|
| viewer | role | Read everything, change nothing. The right choice for a dashboard, an export job, or anything that only looks. |
| member | role | Read and write monitors, projects and channels. What CI needs. |
| admin | role | Everything a member can do, plus billing and settings. |
A key can never have more access than the person who created it. An admin cannot mint an owner key, which stops a key being a quiet route to promoting yourself.
Use it
curl -s https://sysops247.io/api/v1/monitors \
-H "Authorization: Bearer bp_xxxxxxxxxxxxxxxxxxxxxxxx"Store it as an environment variable rather than pasting it into scripts:
export BEACON_API_KEY="bp_xxxxxxxxxxxxxxxxxxxxxxxx"
curl -s https://sysops247.io/api/v1/monitors \
-H "Authorization: Bearer $BEACON_API_KEY" | jqIn GitHub Actions, put it in Settings → Secrets and variables → Actions and read it as ${{ secrets.BEACON_API_KEY }}.
What a key is, and is not
It belongs to the organization, not to you
A key keeps working after you leave, and its changes are attributed to the organization rather than to your user. That is deliberate — a credential that stopped working when someone changed jobs would take a customer's deploy pipeline down with it. Revoke keys when the thing using them is retired, not when people move on.
It carries no plan or balance
A key resolves to your organization; your plan, credit and limits are read fresh on every request. Upgrade, downgrade or top up and the same key reflects it immediately. There is nothing to regenerate, and a key can never be “stuck” on an old tier.
Keys cannot manage keys
Creating and revoking keys requires signing in. A leaked key therefore cannot mint itself a successor that survives you revoking the original — which is the difference between an incident and a permanent problem.
Revoke a key
API keys → Revoke. It stops working immediately, everywhere. The list shows when each key was last used, so you can tell what is still in service before you pull it.
If a key has leaked, revoke it first and investigate second. A revoked key cannot be un-revoked, which is the correct trade in that direction.
Key management endpoints
These are the ones an API key cannot call.
When it does not work
| Field | Type | Notes |
|---|---|---|
| 401 | status | Invalid, revoked, expired, or mistyped. Every one of those returns the same message on purpose — a stolen key should learn nothing from the reply. |
| 403 | status | The key's role is too low. A viewer key cannot write. |
| 429 | status | Too many requests. Back off by the Retry-After header. |
Next: the API reference, or wiring it into CI.