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 credentials.

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": 2, "minor": 0, "revision": 0 },
"authentication": {
"...": "see below"
}
}

Backend apps send version 2.0.0, the version the Server SDKs use. Calling events, messaging, provisioning, and signalwire.receive all require a major version below 4; 4.0.0 is the Client protocol for Call Fabric.

Project and token

Code that runs on your own server can hold your SignalWire credentials directly. Authenticate with your Project ID and an API token, available in the SignalWire Dashboard:

{
"version": { "major": 2, "minor": 0, "revision": 0 },
"authentication": {
"project": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"token": "PT9a8b7c6d5e4f3a2b1c..."
}
}
Keep your API token on the server

Keep your API token on the server. Never ship it to a browser or mobile app — anyone who opens the page can read it and use it against your account. Client apps authenticate with a short-lived JWT instead; see the Client reference.

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 media, included on every successful connect. A backend app that isn’t handling WebRTC media can ignore them.

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": 2, "minor": 0, "revision": 0 },
"authentication": {
"project": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"token": "PT9a8b7c6d5e4f3a2b1c..."
},
"protocol": "signalwire_........",
"authorization_state": "<opaqueAuthState>"
}

Pass contexts in your connect message to start receiving inbound events for those contexts as soon as you connect, rather than subscribing in a separate step. See Events and subscriptions.

Using an SDK

The Server SDKs build and send the signalwire.connect message for you — you provide your project and token when you create the client, and the SDK handles the handshake, the protocol and authorization_state bookkeeping, and reconnection.

Next steps