Authentication

Perceive8 supports two authentication methods for REST requests, plus a query-parameter fallback for WebSocket and SSE connections.

API key (server-side)

API keys are the recommended method for server-to-server integrations. Pass the key in the X-API-Key header:

GET /v1/analyses HTTP/1.1
Host: api.perceive8.com
X-API-Key: pk_live_xxxxxxxxxxxx

Create and revoke keys in the dashboard under Audio → Settings → Developer or via POST /v1/keys. Keys starting with pk_live_ are production keys; pk_test_ keys are used for development.

Bearer token (user-scoped)

For browser or mobile calls on behalf of a signed-in user, pass a Supabase JWT in the Authorization header:

GET /v1/analyses HTTP/1.1
Host: api.perceive8.com
Authorization: Bearer <supabase-jwt>

User-scoped requests are limited to resources the user owns or has workspace access to.

WebSocket and SSE

WebSocket and SSE endpoints cannot send custom headers from the browser. Pass the API key or JWT as a token query parameter:

wss://api.perceive8.com/v1/stream?token=pk_live_xxxxxxxxxxxx

Treat these tokens as secrets. Do not expose them in client-side URLs unless the connection is over TLS.

Forbidden and unauthorized errors

• 401 Unauthorized — the request is missing credentials or the token has expired.
• 403 Forbidden — the credentials are valid but the user or key does not have permission for the resource.

Rotating compromised keys

If a key is exposed, revoke it immediately in the dashboard and create a new one. Webhook secrets can be rotated by deleting the old webhook and creating a new one.