Security

Relay Cloud provides multiple layers of security to protect your real-time infrastructure.

Authentication Methods

Relay supports three authentication strategies for API access:

1. Bearer Token (Recommended)

Create API tokens in your app's Tokens tab. Tokens start with rly_.

curl -H "Authorization: Bearer rly_your_token_here" \
     https://relay.example.com/api/v1/apps/{appId}/events

2. Key + Secret Headers

curl -H "X-Relay-Key: your_app_key" \
     -H "X-Relay-Secret: your_app_secret" \
     https://relay.example.com/api/v1/apps/{appId}/events

3. Pusher-Compatible HMAC

Standard Pusher HMAC signature via query parameters. Compatible with all Pusher SDKs.

API Token Scopes

Tokens can be scoped to limit what they can do:

Scope Allows
events:publish Trigger single events
events:batch Batch trigger events
channels:read List and inspect channels
presence:read Read presence user lists
webhooks:manage Manage webhook endpoints
encryption:manage Manage encryption keys
schemas:manage Manage channel schemas
connections:read List active connections
analytics:read Read usage analytics

Tokens with no scopes defined have full access (backwards compatible).

Two-Factor Authentication

All users can enable TOTP-based 2FA from their Profile settings. Once enabled, a 6-digit code is required on every login.

Organization admins can require 2FA for all team members via Organization Policies.

IP Allowlisting

Restrict API access to specific IP addresses or CIDR ranges per app.

Enable in app Settings → IP Allowlist. Only requests from listed IPs will be accepted; all others get a 403.

Geo-IP Restrictions

Block or allow API access by country. Two modes:

  • Allowlist — Only listed countries can access
  • Blocklist — Listed countries are blocked

Uses MaxMind GeoLite2 database for IP-to-country lookup.

Secret Scanning

Relay automatically scans event payloads for leaked credentials:

  • AWS keys, GitHub tokens, Stripe keys, JWTs
  • Credit card numbers, SSNs, email addresses
  • Private keys, bearer tokens

Three modes per app:

  • Warn — Log a warning, deliver the event
  • Redact — Replace detected secrets with [REDACTED]
  • Reject — Return a 422 and refuse to deliver

E2E Encrypted Channels

Channels prefixed with private-encrypted- use end-to-end encryption:

  1. Client and server exchange X25519 public keys
  2. A shared secret is derived via key exchange
  3. Messages are encrypted with XSalsa20-Poly1305
  4. The relay server cannot read encrypted payloads

Enable E2E encryption in app Settings.

Automatic Key Rotation

Schedule automatic rotation of your app key and secret:

  • Set interval (e.g., every 90 days)
  • Configure grace period (both old and new keys valid during transition)
  • Email notifications when rotation occurs
  • Automatic Redis sync to relay server

Breach Detection

Relay monitors for security threats:

  • Token leaks — If a GitHub Secret Scanning alert detects your token in a public repo, it's automatically revoked
  • Brute force — Repeated auth failures from an IP trigger alerts
  • Auto-lockdown — 3+ unresolved critical security events in an hour automatically disables the app

All security events are visible in the Activity log.

mTLS (Client Certificates)

For enterprise clients, Relay supports mutual TLS authentication:

  1. Register your client's TLS certificate in app settings
  2. Configure your reverse proxy to pass X-Client-Cert-Fingerprint
  3. Relay validates the certificate against the registry

Set mtls_required: true to reject connections without a valid client cert.