Authentication

API keys

The realtimeodds gateway authenticates every WebSocket connection by API key. You receive your key out-of-band — there is no public sign-up flow during alpha. Contact us for a key.

Keys are opaque strings (≥16 characters). Treat them like passwords: store them in a secret manager, never commit them to source control, never expose them in browser bundles you ship publicly.

Passing the key

The SDK appends the key to the WebSocket URL automatically:

const client = createClient({
  url: 'wss://api.realtimeodds.xyz',
  apiKey: process.env.REALTIMEODDS_API_KEY!
})

Under the hood the client opens wss://api.realtimeodds.xyz/?apiKey=<key>. You don’t need to construct the URL yourself.

Browser usage

A key embedded in a browser bundle is visible to anyone who opens dev tools. For public-facing sites, proxy through your own backend instead of calling the gateway directly with a long-lived key.

Close codes

If authentication fails, the gateway closes the WebSocket immediately — before any handshake — with one of these close codes:

Code	Meaning
4001	Missing apiKey query parameter
4002	Invalid or unknown apiKey
4003	Quota or rate limit exceeded (reserved — not enforced today)

The SDK surfaces these as fatal errors:

client.on('error', ({ message, fatal }) => {
  if (fatal) {
    console.error('auth or unrecoverable error:', message)
  }
})

try {
  await client.connect()
} catch (err) {
  // connect() rejects with the same fatal-error message.
  console.error('failed to connect:', err)
}

When the SDK receives a 4001/4002/4003 close code, it stops reconnecting and emits a fatal error event. You don’t want exponential backoff on a bad credential — that would just hammer the gateway.

For non-auth disconnects (network blips, gateway restarts), the SDK reconnects automatically with exponential backoff — see Reconnect tuning.

Rotating a key

If you need to rotate, get a new key, redeploy with the new value, and disconnect any open clients holding the old one. Keys do not expire automatically.