Authentication

Three ways to send your key

All three methods are equivalent for REST. Use whichever fits your HTTP client best.

Option A: Authorization header (bearer token)

Authorization: Bearer vera_oG8HGbqOz6cfvsORNORRkaA...

Option B: X-API-Key header

X-API-Key: vera_oG8HGbqOz6cfvsORNORRkaA...

Option C: Query parameter

GET /pm/v2/news?api_key=vera_oG8HGbqOz6cfvsORNORRkaA...

The query parameter is primarily useful for WebSocket connections, where setting custom headers on the upgrade request is not always possible. For REST calls, prefer a header to keep keys out of server logs.

If both headers are present, X-API-Key takes precedence when it starts with vera_.

Example with curl

# Using Authorization header (recommended)
curl https://ai-hub.cryptobriefing.com/pm/v2/news \
     -H "Authorization: Bearer $VERA_KEY"

# Using X-API-Key header
curl https://ai-hub.cryptobriefing.com/pm/v2/news \
     -H "X-API-Key: $VERA_KEY"

# Using query parameter (useful for WebSocket; avoid for REST)
curl "https://ai-hub.cryptobriefing.com/pm/v2/news?api_key=$VERA_KEY"

Key format

Every key starts with the vera_ prefix followed by a 43-character URL-safe base64 suffix (256 bits of entropy from 32 random bytes). Example: vera_oG8HGbqOz6cfvsORNORRkaA629G0hjcDJqXrVQLV7lo.

Issuance

You generate your own keys from the dashboard. Sign in with your social login (Google, GitHub, or email), then click + New key.

• First key. Sign in to the dashboard and generate your first vera_* key — it activates immediately and is included with your plan.
• Rotation. Open the dashboard, generate a new key, then revoke the old one. The old key continues to work for a 5-minute grace window so in-flight requests complete cleanly.
• Additional keys. Create labelled keys for different environments (e.g. staging, research) directly from the dashboard. Pro subscriptions support up to five concurrent keys; Free and Builder accounts get one.

Rotation

Rotation is self-serve from the dashboard. Generate a new key, deploy it through your fleet, then revoke the old one. The old key continues to work for a 5-minute grace window after revocation so that in-flight requests complete cleanly. After that, the old key returns 401.

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. Extract the API key from the Authorization: Bearer header, the X-API-Key header, or the api_key query parameter.
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 signal and news endpoints.
• markets.read: read access to market data within the feeds.

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; generate a new key from the dashboard to pick up newly available scopes.

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 ai-hub.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.