Skip to navigation

Authentication

View as MarkdownOpen in Claude

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:

{
"version": { "major": 4, "minor": 0, "revision": 0 },
"authentication": {
"...": "see below"
}
}

Authenticate with a JWT

Never put an API token in a client app

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:

{
"version": { "major": 4, "minor": 0, "revision": 0 },
"authentication": {
"jwt_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...."
}
}

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:

{
"identity": "c1a2b3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"authorization": { },
"protocol": "signalwire_........"
}
FieldDescription
identityA unique identifier for this client, valid for the life of the connection.
authorizationThe permissions and scopes granted to this connection. Treat it as opaque. To reconnect, pass back the authorization_state from the signalwire.authorization.state event (below) — not this object.
protocolThe protocol identifier to use on your subsequent requests.
ice_serversSTUN/TURN servers for negotiating WebRTC media. At least one is always included on a successful connect.

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:

{
"authorization_state": "<opaqueAuthState>"
}

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:

{
"version": { "major": 4, "minor": 0, "revision": 0 },
"authentication": {
"jwt_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...."
},
"protocol": "signalwire_........",
"authorization_state": "<opaqueAuthState>"
}

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.

Next steps