Credentials

Bearer authentication

Authenticate every request with a Bearer token:

Authorization: Bearer rray_live_...

A missing, malformed or revoked credential returns 401 auth.unauthorized. Every response carries an RRay-Request-Id header — quote it to support.

The public error catalog (GET /errors and GET /errors/{code}) is the one unauthenticated surface: it is the dereference target of the type URL on every error, so it has to be readable without a key.

Two kinds of credential

A workspace key is the recommended send credential. It carries its workspace, so it never names one per request. The secret is shown once at creation; we store only a peppered hash. Revoking a key takes effect immediately.

A platform key acts for the whole account: it can send mail and manage account-level resources (workspaces, billing limits, keys). Because it is not tied to a workspace, it must name the target workspace on every operation that acts in one.

The workspace header

RRay-Workspace-Id selects the workspace for a single-workspace operation: sending, listing messages, reading one message or its body. Proprietary headers are RRay--prefixed; there are no X- headers in this API.

A workspace key rejects the header rather than ignoring it — even when the value matches its own workspace. Silently accepting it would let you believe the header was routing somewhere it never was.

{
  "type": "https://api.rray.app/errors/validation.workspace_header_invalid",
  "title": "Invalid workspace header",
  "status": 400,
  "code": "validation.workspace_header_invalid",
  "category": "validation",
  "detail": "The workspace header does not match the grammar this endpoint expects.",
  "request_id": "36661076a55a4275bb6acc7714494f1f",
  "instance": "/v1/messages",
  "invalid_params": [
    {
      "field": "RRay-Workspace-Id",
      "message": "Workspace headers are not accepted with a workspace-scoped API key — the key already pins its workspace.",
      "kind": "workspace_header_invalid"
    }
  ]
}

A foreign or unknown workspace id always returns workspace.not_found — we never reveal whether an id exists under another account. The header rules, including the plural RRay-Workspace-Ids on GET /v1/stats, are laid out per operation in Workspaces.

Which operations need the header

Errors you can get from a credential

Keeping keys safe

• Keys are bearer secrets. Send them from your server, never from a browser or a mobile app.
• Use rray_test_... for development and rray_live_... for production, so a mistake in one cannot send real mail from the other.
• Rotate by minting the new key, deploying it, then revoking the old one. Revocation is immediate, so the overlap matters.
• Minting more keys for a workspace does not raise its rate limit — they share one budget.