API Tokens
API tokens provide scoped, revocable access to the Relay API. Use them instead of your app key/secret for production integrations.
Creating Tokens
Go to your app → Tokens tab → Create Token.
Each token gets:
- A name for identification
- An optional description
- Scopes that limit what the token can do
- An optional rate limit override
The full token (starting with rly_) is shown once. Copy it immediately.
Using Tokens
Pass the token as a Bearer token in the Authorization header:
curl -X POST /api/v1/apps/{appId}/events \
-H "Authorization: Bearer rly_abc123..." \
-H "Content-Type: application/json" \
-d '{"name":"my-event","channels":["my-channel"],"data":"{\"hello\":\"world\"}"}'
Scopes
Scopes restrict what a token can do. A token without scopes has full access.
| Scope | Permission |
|---|---|
events:publish |
Trigger single events |
events:batch |
Batch trigger events |
channels:read |
List and inspect channels |
channels:manage |
Create and manage channels |
presence:read |
Read presence channel data |
webhooks:manage |
Manage webhook endpoints |
encryption:manage |
Manage encryption keys |
schemas:read |
Read channel schemas |
schemas:manage |
Create and manage schemas |
functions:manage |
Manage edge functions |
connections:read |
List active connections |
connections:manage |
Disconnect connections |
analytics:read |
Read usage analytics |
app:read |
Read app configuration |
app:manage |
Modify app settings |
Category Wildcards
Use events:* to grant all event-related scopes.
Rate Limiting
Each token can have its own rate limit, or inherit the app's default rate limit profile.
Built-in rate limit profiles:
- Burst Friendly — 120 req/min, 200 burst
- Steady Stream — 60 req/min, 30 burst
- API Heavy — 300 req/min, 500 burst
- Restricted — 10 req/min, 5 burst
Token Expiration
Tokens can have an expiration date. Expired tokens automatically return 401 Unauthorized.
Revoking Tokens
Revoke a token immediately from the Tokens tab. The token stops working instantly — no grace period.
Best Practices
- One token per integration — If one is compromised, revoke it without affecting others
- Use the minimum scopes needed — A frontend client only needs
channels:read - Set expiration dates for temporary integrations
- Rotate tokens regularly — Old tokens should be revoked after rotation
- Never commit tokens to git — Use environment variables