Authentication
A WebSocket handshake has no Authorization header, so Relay authenticates differently from the REST API: you open the socket first, then log in with your first message. That message is signalwire.connect, and it carries your credential.
If your first message is anything other than signalwire.connect, the service closes the socket without sending a response. It also closes a socket that hasn’t sent signalwire.connect within about 5 seconds of opening. Once signalwire.connect succeeds, the connection is authenticated for its entire lifetime, and every later command reuses it.
The connect message
signalwire.connect takes two required parameters — the protocol version your client speaks and an authentication object — plus a few optional ones:
Authenticate with a JWT
Never ship a project API token to a browser or mobile app. Anyone who opens your page can read it and use it against your account. Client apps authenticate with a short-lived token instead.
Your backend generates a short-lived JWT (using its own SignalWire credentials) and hands it to the client, which sends it as jwt_token:
For Call Fabric, the token you generate is a Subscriber Access Token — a JWT scoped to a single subscriber (the signed-in end user). Either way, the client only ever holds a short-lived token, never your account credentials.
Advanced: if your token is client-bound (DPoP), also send a dpop_token in the connect message to cryptographically bind the connection to your client. Leave it unset for standard JWT/SAT authentication.
What you get back
A successful signalwire.connect returns your connection details:
Refreshing your token
Because the JWT is short-lived, refresh it before it expires without dropping the connection: send signalwire.reauthenticate with a fresh token. See Connection lifecycle.
Reconnecting
Right after a successful connect — and periodically afterward — you receive a signalwire.authorization.state event:
Save the latest authorization_state. If the socket drops, you can reconnect quickly by sending signalwire.connect again with the saved state and the protocol you were given:
Using an SDK
The Browser SDK builds and sends the signalwire.connect message for you — you provide the token when you create the client, and the SDK handles the handshake, the protocol and authorization_state bookkeeping, token refresh, and reconnection. See the Browser SDK authentication guide.