Authentication & Workspaces | rray — Transactional Email API

API keys

Authenticate every request with a Bearer token:

Authorization: Bearer rray_live_...

Keys are created in the dashboard and come in two modes — live and test. The secret is shown once at creation; we store only a peppered hash. Revocation (DELETE /v1/api-keys/{id}) takes effect immediately.

Workspaces

A workspace is a sending tenant inside your account: its own egress pool and its own email history. Every account starts with a default workspace; create more with POST /v1/workspaces (for example, one per product or environment).

Key scopes

Scope	Behaviour
`platform` (default)	Can act on any of your workspaces — every send must name one via the `X-Workspace-Id` header
`workspace`	Bound to a single workspace — no header needed, sends are routed there automatically

Sending with a platform key and no X-Workspace-Id fails with validation.workspace_header_required; naming a workspace that isn’t yours fails with workspace.not_found (we never reveal other tenants’ ids).

Rate limits

Send-path requests are limited per API key (per-minute fixed window). Every response carries the current budget:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
X-RateLimit-Reset: 1751700000

On 429 rate_limit.exceeded, honour Retry-After (seconds) before retrying.

Dashboard sessions

The dashboard itself signs in through our identity provider and manages keys over the same API (/v1/api-keys accepts dashboard sessions only — an API key cannot mint other keys).