Authentication

Server-Side API Authentication

Three methods to authenticate REST API requests:

1. Header-Based (Simplest)

curl -X POST /api/v1/apps/{appId}/events \
  -H "X-Relay-Key: YOUR_KEY" \
  -H "X-Relay-Secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "event", "channels": ["ch"], "data": "{}"}'

2. Bearer Token

Create an App Token in the dashboard, then:

curl -X POST /api/v1/apps/{appId}/events \
  -H "Authorization: Bearer rly_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "event", "channels": ["ch"], "data": "{}"}'

3. Pusher-Compatible HMAC

For clients that implement the Pusher HTTP API signing protocol. Query parameters auth_key, auth_timestamp, auth_version, body_md5, and auth_signature are validated against your app secret.

Client-Side Channel Authentication

When a client subscribes to a private- or presence- channel, the Relay server returns an auth_required response. The client then calls your auth endpoint to get a signed token.

Auth Endpoint

By default, the JS client POSTs to /broadcasting/auth. Configure it:

const relay = new Relay('key', {
    authEndpoint: '/api/v1/apps/YOUR_APP_ID/auth',
    // or for custom auth:
    auth: {
        headers: {
            'X-CSRF-Token': document.querySelector('meta[name="csrf-token"]').content,
        },
    },
});

Auth Response Format

For private channels:

{"auth": "key:hmac_sha256_signature"}

For presence channels:

{
    "auth": "key:hmac_sha256_signature",
    "channel_data": "{\"user_id\":\"123\",\"user_info\":{\"name\":\"Tom\"}}"
}

Signature Computation

signature = HMAC-SHA256(secret, socket_id + ":" + channel_name)
auth = key + ":" + hex(signature)

For presence channels:

signature = HMAC-SHA256(secret, socket_id + ":" + channel_name + ":" + channel_data)

App Tokens

Create tokens in the dashboard under Apps > Tokens. Tokens are hashed with SHA-256 — the plain token is shown once on creation. Tokens can have expiration dates and are tracked with last_used_at.