> ## Documentation Index
> Fetch the complete documentation index at: https://relay-demo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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.

![Sequence diagram of OAuth with PKCE between the user's browser, the third-party app server, Relay's authorization server and the Relay API: redirect to authorize, sign in and approve scopes, redirect back with a code, exchange the code and verifier for tokens, call the API with the access token.](https://mintcdn.com/relay-demo/g4EzaOdLYNrmsxJ6/images/oauth-pkce.png?fit=max\&auto=format\&n=g4EzaOdLYNrmsxJ6\&q=85\&s=fe22f2cd433f1228a92353d79ea82d01)

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:

```text theme={null}
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:

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.