Authentication

The header

Send your API key as a bearer token on the Authorization header. This applies to every REST request and to the WebSocket upgrade request.

Authorization: Bearer vera_live_aBcDeFgHiJkLmNoPqRsTuVwX

Key format

Keys are prefixed by environment. The prefix tells you at a glance which environment a key belongs to; the rest is a 24-character random suffix with about 120 bits of entropy.

Issuance

New keys are issued in three situations:

• Trial start. Signing up locks your founding rate; your vera_live_* key is issued by email the day we launch, when your 7-day free trial begins. (After launch, new sign-ups receive their key within minutes of checkout.) The first 50 customers may receive their keys manually; from customer 51 onward this is fully webhook-driven.
• Manual rotation. During early access, email vera@cryptobriefing.com to rotate any active key. We generate a new key, revoke the old key, and surface the new value once. (Self-serve rotation from a dashboard is coming.)
• New environment. Email us to add a labelled key (e.g. staging, research). Each Founding-tier subscription supports up to six concurrent keys.

Rotation

Rotation is a single-step operation. When you rotate, the old key continues to work for a 5-minute grace window so that in-flight requests from your fleet complete cleanly. After that, the old key returns 401.

For zero-downtime rotation, run with both keys active for the duration of your deploy: request a new key first, deploy it through your fleet, then ask us to revoke the old one once metrics confirm the new key is in use.

Revocation triggers

A key can be marked as revoked (permanent) or suspended (temporary). The differences:

What the gateway looks at

Every request reaches the API gateway, which performs a short check against your key's state and your subscription's state:

1. Strip the bearer token from the header and look up the key by its prefix.
2. Verify the hash matches. (Unknown key → 401.)
3. Check key status: active → continue, suspended → 402 Payment Required, revoked → 401 Unauthorized.
4. Check the associated subscription state (in our cache, refreshed by Stripe webhooks). trialing / active → continue; otherwise route to the appropriate error.
5. Check rate-limit counters. Over → 429 Too Many Requests with Retry-After.
6. Forward the request to the underlying service.

Scopes

Every key carries a set of scopes. Today, only two scopes exist and every key gets both:

• events.read: read access to the event stream and REST endpoints.
• markets.read: read access to the market registry and snapshots.

Future scopes will allow write operations (e.g. annotations.write) and finer-grained read partitions (e.g. events.read.kalshi). Scopes are designed to be additive. Existing keys will not silently gain new scopes; email us to opt in.

Security recommendations

• Treat keys as you would database credentials. Never commit to a repo, never log, never paste into chat.
• Use a separate key per environment so a staging leak does not require touching production.
• Rotate keys whenever someone with access to them leaves the team.
• Restrict outbound calls to api.vera.cryptobriefing.com and stream.vera.cryptobriefing.com at your egress firewall so a malicious dependency cannot exfiltrate the key to an attacker-controlled endpoint.
• If you believe a key is compromised, rotate immediately and then email security@cryptobriefing.com so we can audit the access pattern from our side.