Authentication & Scopes

Bearer token authentication, key scopes, and least-privilege key design.

Bearer token authentication

Every request must include an Authorization header:

Authorization: Bearer YOUR_API_KEY

No or an unknown key: HTTP 401. A key without the scope the request needs: HTTP 403. Most endpoints answer 403 with an error naming the missing scope; some also include "code": "API_KEY_SCOPE" and the scope in required. Your organization's allowed IP ranges (Settings → Security policy) apply to keys too.

API key scopes

Scopes are <area>:read or <area>:write. Write includes read for the same area. Give each key the fewest it needs:

Whatever its scopes, no key can reach anything outside this API: not the vault, terminals, members, billing, settings, other keys, or bulk alert acknowledgement. Those need a person signed in.

Key rotation

An org owner rotates a key from Developer → API Keys or with POST /api/v1/keys/:keyId/rotate (signed in, not with a key). The old secret stops working within 15 seconds; there is no grace period beyond that. The new one is shown once.

For zero-downtime rotation: create a new key, switch your integration to it, check it works, then revoke the old one.

Webhook signature verification

Deliveries carry X-Watch-Signature: sha256=<hex>, the HMAC-SHA256 of the raw body keyed with the endpoint's secret. See API: Webhooks → Signature verification for working code. The body's own ts is signed; the X-Watch-Timestamp header is not. (The X-Watch- names come from the product's earlier name.)

Tips

All Vigilhold docs · Start a 14-day free trial