Skip to content
RelayDocumentation

GuidesGet started

Authentication

Authenticate API requests with secret keys, and keep test and live data apart.

The Relay API uses secret API keys. Send yours in the Authorization header as a bearer token on every request:

curl https://api.relay.dev/v1/events \
  -H "Authorization: Bearer rk_test_51Hx9a2f7c1d"

Requests without a valid key return 401 Unauthorized. See Errors.

Test and live mode

Every account has two separate environments. Events, endpoints and logs never cross between them.

Test modeLive mode
Key prefixrk_test_rk_live_
DeliveriesTo any URL, including the inspectorOnly to HTTPS URLs
Retention7 days30 days (90 days on Scale)
BillingFreeCounts toward your plan

Key permissions

When you create a key you can restrict what it does. Use the narrowest key for each service.

PermissionAllows
events:writeSend events
events:readList and retrieve events and deliveries
endpoints:writeCreate, update and delete endpoints
endpoints:readList and retrieve endpoints

Treat keys like passwords

A live key with endpoints:write can redirect your customers' webhooks. Store keys in a secrets manager, rotate them when someone leaves the team, and never ship them to a browser or mobile app.

Rotating a key

  1. Create a new key with the same permissions.
  2. Deploy it to your services.
  3. Check Last used on the old key in the dashboard. When it stops changing, delete it.

Deleting a key takes effect within a few seconds everywhere.