Skip to main content

Authentication

The WebSocket feed authenticates at the handshake, using the same API key as the REST API. The key is passed as a token query parameter on the connection URL. There is no login message and no Authorization header.

wss://trading-ws.vertex-api.com/ws?token=<your-token>
note

This differs from the REST API, which sends the key as an Authorization: Bearer <token> header. On the WebSocket feed the same key goes in the query string instead. There is no separate WebSocket credential.

How it works​

The server validates the token during the WebSocket upgrade, before the connection is established:

  • Valid key: the handshake completes (101 Switching Protocols) and the connection opens. The key's entitlements (which sports, competitions, and channels you may receive) are bound to the session.
  • Missing, malformed, or revoked key: the server rejects the upgrade with HTTP 401 and no WebSocket connection is opened. This surfaces in most clients as a connection error at connect() time, not as a close frame.

Because authentication happens at the handshake, an authentication failure is an HTTP error, not an in-stream message. Handle it where you handle connection failures.

Entitlements​

The key determines what you can receive. Subscribing to a channel your key is not entitled to is rejected per-subscription rather than closing the connection (see Subscriptions). Within an entitled channel, you receive only the sports and competitions your key covers.

Token handling​

  • Treat the token as a secret. Because it appears in the connection URL, avoid logging full WebSocket URLs and avoid embedding the token in client-side code that ships to browsers.
  • Always connect over wss:// (TLS). The token is only protected in transit under TLS.
  • Partner API keys are long-lived and do not expire on a timer. If a key is rotated or revoked, existing connections using it will fail to re-establish. Reconnect with the new key.

To request or rotate a key, contact your integration manager.