Skip to main content
A Slack digest bot, an internal dashboard, or a BI pipeline that surfaces your fired alerts has no business holding a key that can also create, edit, or delete alert rules. Scope it down to read:alerts and a compromised or misbehaving integration can look, but not touch.

​
1. Mint a read:alerts-only key

Keys are minted in the Developer Portal under your organization’s API Keys settings (see Authentication). Minting a key with a specific scope subset requires the minting key or user to hold admin:keys. When creating the key, select only read:alerts — leave write:alerts (and every other scope your integration doesn’t need) unchecked. The resulting key is prefixed sk_live_, same as any other key.
write:alerts implicitly grants read:alerts — a full read/write alerts key can do everything a read-only key can. Going the other way isn’t true: a read:alerts-only key can never create, update, toggle, or delete a rule. See the full table on the Scopes page.

​
2. Verify what it can do

Reads succeed:
curl
curl -H "Authorization: Bearer $ALTERSCOPE_API_KEY" \
  "https://api.alterscope.org/v1/alerts/rules"

curl -H "Authorization: Bearer $ALTERSCOPE_API_KEY" \
  "https://api.alterscope.org/v1/alerts/events?limit=20"
Writes fail closed with 403:
curl
curl -H "Authorization: Bearer $ALTERSCOPE_API_KEY" \
     -H "Content-Type: application/json" \
     -X POST -d '{"name": "test", ...}' \
  "https://api.alterscope.org/v1/alerts/rules"
# 403 insufficient_scope
Same result for PUT, DELETE, and the /toggle endpoint — a read-only key gets 403 on all of them, not a silent no-op.

​
3. Use it from your integration

python
from alterscope import AlterscopeClient

# A key holding only read:alerts — this client can list/inspect
# rules and events, and nothing else.
client = AlterscopeClient(api_key="sk_live_...")

rules = client.get("/v1/alerts/rules")["rules"]
events = client.get("/v1/alerts/events", params={"limit": 50})["data"]

for e in events:
    print(e["triggered_at"], e["status"], e["data_snapshot"])
This is the same client and the same endpoints as Create and manage alert rules — the only difference is which scope the key underneath was minted with.

​
Troubleshooting

  • 403 insufficient_scope on a call you expected to work: list/get on /v1/alerts/rules and /v1/alerts/events only need read:alerts — if you’re getting 403 there, the key wasn’t actually minted with that scope. Re-check it in the Developer Portal.
  • Need the integration to also pause or edit rules later: don’t loosen the existing key — mint a second key with write:alerts and use it only for the write path. Keeping read and write traffic on separate keys makes it obvious from request logs which key did what.
  • Rotating a read-only key: same process as any other key — mint the replacement, cut the integration over, then revoke the old one. See Rotation and revocation.