Authentication

Every request to Raeh (REST or WebSocket) carries an API key. That's all there is to authentication.

Keys are prefixed raeh_, scoped to your account, and minted in the dashboard.

Create a key

1. Open API Keys in the dashboard sidebar.
2. Click Create key, give it a label (e.g. firmware-prod, ios-app).
3. Copy the key. It looks like raeh_ABCdef123…. Save it now. The dashboard never shows it again.

You can create as many keys as you want. A single revoke doesn't affect the others.

Use the key

The key can go in either of two places:

Authorization header (REST, or WebSocket subprotocol if your client supports it):

Authorization: Bearer raeh_ABCdef123...

Query parameter (convenient for WebSockets in browsers, where headers aren't easily settable):

wss://api.raeh.io/stream/ingest?api_key=raeh_ABCdef123...&device_id=...

Both are first-class. Pick whichever is easier for your runtime.

Key scope

A key is bound to one account: yours. It can:

• Connect to /stream/ingest as any device under your account
• Subscribe to /stream/subscribe and receive insights for any session under your account
• Call REST endpoints (/v1/device-models, /v1/sessions, /v1/insights) for your account

A key can't read another account's data. Ever.

Two deployment patterns

Shared key

Ship one key inside your firmware / app, used by every end-user.

• Pros: zero server infrastructure on your side.
• Cons: a user extracting the key from their app can stream arbitrary data into your account, and you can't revoke just one user.
• Good for: proof-of-concept, internal tools, small pilots.

Per-user keys

Your backend mints a fresh raeh_* key per end-user (or per device) and hands it to the client on login.

• Pros: revoke any single user without affecting the rest; clear per-user audit trail; rate-limit per user.
• Cons: you need a backend endpoint that creates keys (we'll document the programmatic key-minting API soon).
• Good for: production consumer apps.

Start with shared-key for the first prototype. Move to per-user keys before you ship to real users.

Rotation and revoke

• Rotate: create a new key, roll your fleet over to it, then delete the old one.
• Revoke: delete a key in the dashboard. It stops working immediately; any open WebSocket using that key is closed.

There's no "expiry" today; keys live until you delete them.

Where keys should not go

• Client-side JavaScript on a public website. Anyone can view-source it. Only embed keys in firmware or native app bundles where extraction is harder (not impossible) or use a short-lived token minted per session by your backend.
• Git commits. Use a secrets manager or environment variables.
• Shared screenshots. (It happens.) Rotate immediately if a key is exposed.