> This page is for APIs.

> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# Authentication

> Authenticate a browser or mobile Relay connection by sending signalwire.connect with a short-lived JWT as the first WebSocket message.

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:

```json
{
  "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`:

```json
{
  "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.

> **Tip**
>
> 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:

```json
{
  "identity": "c1a2b3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "authorization": { },
  "protocol": "signalwire_........"
}
```

| Field           | Description                                                                                                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `identity`      | A unique identifier for this client, valid for the life of the connection.                                                                                                                              |
| `authorization` | The 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. |
| `protocol`      | The protocol identifier to use on your subsequent requests.                                                                                                                                             |
| `ice_servers`   | STUN/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](/docs/apis/relay/client/connection-lifecycle).

## Reconnecting

Right after a successful connect — and periodically afterward — you receive a `signalwire.authorization.state` event:

```json
{
  "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:

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

## Using an SDK

The [Browser SDK](/docs/browser-sdk/v4/guides/overview) 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](/docs/browser-sdk/v4/guides/authentication).

## Next steps

#### [Overview](/docs/apis/relay/client)

How a Relay connection works end to end, and what each service does.

#### [Errors](/docs/apis/relay/client/errors)

Read the result on every response to tell success from failure.