Authentication

Use an API key for your own account, or OAuth when your app acts for other Relay customers.

API keys

Send your key as a bearer token on every request:

curl https://api.relay.example/v1/events \
  -H "Authorization: Bearer rk_live_..."

Prefix	Use
rk_test_	Test mode. Deliveries only go to test endpoints and the CLI.
rk_live_	Live mode.

Create and revoke keys in the dashboard under Developers → API keys. A key is shown once; store it in your secrets manager, never in your repository or in client-side code. Give each service its own key so you can revoke one without touching the others.

OAuth for apps

If you are building an app that other Relay customers connect to, such as an integration in a marketplace, don’t ask them for an API key. Register an OAuth app in the dashboard and use the authorization code flow with PKCE. Your app gets a token scoped to what the customer approved.

The customer approves your app once; your server exchanges the code for tokens and calls the API with the access token.

Send the customer to the authorize page:

https://dashboard.relay.example/oauth/authorize
  ?client_id=app_9f2c
  &redirect_uri=https://yourapp.example/relay/callback
  &scope=events:write endpoints:read
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=af0ifjsldkj

Then exchange the code from the callback on your server:

curl https://api.relay.example/oauth/token \
  -d grant_type=authorization_code \
  -d code=ac_7Hk2... \
  -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk \
  -d client_id=app_9f2c \
  -d redirect_uri=https://yourapp.example/relay/callback

Access tokens last one hour. Use the refresh token with grant_type=refresh_token to get a new one; each refresh returns a new refresh token, and the old one stops working.

Scopes

Scope	Allows
events:write	Send events.
events:read	Read events and their deliveries.
endpoints:read	List endpoints and subscriptions.
endpoints:write	Create, change and delete endpoints.

Ask for the fewest scopes your app needs. Customers see the list before they approve.