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 mode | Live mode | |
|---|---|---|
| Key prefix | rk_test_ | rk_live_ |
| Deliveries | To any URL, including the inspector | Only to HTTPS URLs |
| Retention | 7 days | 30 days (90 days on Scale) |
| Billing | Free | Counts toward your plan |
Key permissions
When you create a key you can restrict what it does. Use the narrowest key for each service.
| Permission | Allows |
|---|---|
events:write | Send events |
events:read | List and retrieve events and deliveries |
endpoints:write | Create, update and delete endpoints |
endpoints:read | List 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
- Create a new key with the same permissions.
- Deploy it to your services.
- 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.