Authentication

Every endpoint except GET /health requires your bearer token. There are no signatures to compute, no secrets to exchange and no sessions to refresh — one header, on every request.

The header

The token is presented with the HTTP Bearer scheme, on every request. There is no query parameter alternative and no cookie.

Authorization: Bearer rh_your_token_here

import os, requests

res = requests.get(
    "https://api.ravenhook.dev/namespace",
    headers={"Authorization": f"Bearer {os.environ['RAVENHOOK_TOKEN']}"},
)

const res = await fetch("https://api.ravenhook.dev/namespace", {
  headers: { Authorization: `Bearer ${process.env.RAVENHOOK_TOKEN}` },
});

curl -s "https://api.ravenhook.dev/namespace" \
  -H "Authorization: Bearer $RAVENHOOK_TOKEN"

Where your token comes from

It is shown once, immediately after your subscription starts, and it is never displayed again. We store only a SHA-256 digest of it, so we cannot read it back or email it to you — not as a policy, but because the original does not exist anywhere on our side.

Put it in an environment variable or your CI provider's secret store. Do not commit it: anyone holding it can read every message in your namespace.

If you lose it

Email support@ravenhook.dev from the address on your subscription and we will issue a new one against the same namespace. Your existing addresses keep working — the namespace belongs to the account, not to the key.

Ask us to revoke the old token at the same time if you think it was exposed.

Your token determines your namespace

You never send your namespace as a parameter. The token already identifies which namespace you own, and a second source of truth could only disagree with the first.

Send the full address to endpoints that take one:

address=mfa@ex4mple0ns.inbox.ravenhook.dev   correct
address=mfa                                 rejected

What failure looks like

That last row is a design decision rather than an accident. If a foreign address returned 403 and an empty one returned 404, the difference would let anyone map which namespaces exist. Both return the same thing, so the API cannot be used to enumerate customers.