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

# signalwire.connect

GET /

Authenticate and establish a Relay connection

Reference: https://signalwire.com/docs/apis/relay/client/signalwire/signalwire-connect

## AsyncAPI Specification

```yaml
asyncapi: 2.6.0
info:
  title: signalwire.connect
  version: subpackage_signalwireConnect.signalwire.connect
  description: Authenticate and establish a Relay connection
channels:
  /:
    description: Authenticate and establish a Relay connection
    publish:
      operationId: subpackage_signalwireConnect.signalwire.connect-publish
      summary: signalwire.connect response
      message:
        name: onSignalwireConnectResponse
        title: signalwire.connect response
        payload:
          $ref: '#/components/schemas/signalwire.connect_signalwireConnectResponse'
    subscribe:
      operationId: subpackage_signalwireConnect.signalwire.connect-subscribe
      summary: signalwire.connect
      message:
        name: signalwireConnect
        title: signalwire.connect
        payload:
          $ref: '#/components/schemas/signalwire.connect_signalwireConnectRequest'
servers:
  production:
    url: wss://relay.signalwire.com/
    protocol: wss
    x-default: true
components:
  schemas:
    ChannelsSignalwireConnectMessagesSignalwireConnectResponseJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsSignalwireConnectMessagesSignalwireConnectResponseJsonrpc
    Signalwire.IceServer:
      type: object
      properties:
        urls:
          type: array
          items:
            type: string
          description: The ICE server URLs.
        credential:
          type: string
          description: The credential (password) for connecting to these ICE servers.
        credentialType:
          type: string
          description: The credential type. Currently always `password`.
        username:
          type: string
          description: The username to authenticate against these ICE servers.
        iceTransportPolicy:
          type: string
          description: The ICE transport policy for this server, when set (e.g. `relay`).
      required:
        - urls
        - credential
        - credentialType
        - username
      description: A STUN/TURN ICE server to use for media in WebRTC connections.
      title: Signalwire.IceServer
    Signalwire.ConnectResult:
      type: object
      properties:
        protocol:
          type: string
          description: The protocol identifier to use on your subsequent requests.
        identity:
          type: string
          description: >-
            A unique identifier for this client, valid for the life of the
            connection.
        authorization:
          type: object
          additionalProperties:
            description: Any type
          description: >-
            The authorization granted to this connection — the permissions and
            scopes in

            effect. Treat it as opaque. To restore your session on reconnect,
            use the

            `authorization_state` from the `signalwire.authorization.state`
            event, not

            this object.
        ice_servers:
          type: array
          items:
            $ref: '#/components/schemas/Signalwire.IceServer'
          description: >-
            ICE servers to use for media. Returned on every successful connect,
            including server connections that carry no media — at least one
            entry is always included.
      required:
        - protocol
        - identity
        - authorization
        - ice_servers
      description: >-
        The result of a successful `signalwire.connect`: the `protocol` to use
        on later

        requests, your `identity` and `authorization`, and ICE servers for
        media.
      title: Signalwire.ConnectResult
    JsonRpcErrorCode0:
      type: string
      enum:
        - '-32000'
      title: JsonRpcErrorCode0
    JsonRpcErrorCode1:
      type: string
      enum:
        - '-32001'
      title: JsonRpcErrorCode1
    JsonRpcErrorCode2:
      type: string
      enum:
        - '-32002'
      title: JsonRpcErrorCode2
    JsonRpcErrorCode3:
      type: string
      enum:
        - '-32003'
      title: JsonRpcErrorCode3
    JsonRpcErrorCode4:
      type: string
      enum:
        - '-32004'
      title: JsonRpcErrorCode4
    JsonRpcErrorCode5:
      type: string
      enum:
        - '-32005'
      title: JsonRpcErrorCode5
    JsonRpcErrorCode6:
      type: string
      enum:
        - '-32600'
      title: JsonRpcErrorCode6
    JsonRpcErrorCode7:
      type: string
      enum:
        - '-32601'
      title: JsonRpcErrorCode7
    JsonRpcErrorCode8:
      type: string
      enum:
        - '-32602'
      title: JsonRpcErrorCode8
    JsonRpcErrorCode9:
      type: string
      enum:
        - '-32603'
      title: JsonRpcErrorCode9
    JsonRpcErrorCode10:
      type: string
      enum:
        - '-32700'
      title: JsonRpcErrorCode10
    JsonRpcErrorCode:
      oneOf:
        - $ref: '#/components/schemas/JsonRpcErrorCode0'
        - $ref: '#/components/schemas/JsonRpcErrorCode1'
        - $ref: '#/components/schemas/JsonRpcErrorCode2'
        - $ref: '#/components/schemas/JsonRpcErrorCode3'
        - $ref: '#/components/schemas/JsonRpcErrorCode4'
        - $ref: '#/components/schemas/JsonRpcErrorCode5'
        - $ref: '#/components/schemas/JsonRpcErrorCode6'
        - $ref: '#/components/schemas/JsonRpcErrorCode7'
        - $ref: '#/components/schemas/JsonRpcErrorCode8'
        - $ref: '#/components/schemas/JsonRpcErrorCode9'
        - $ref: '#/components/schemas/JsonRpcErrorCode10'
      title: JsonRpcErrorCode
    JsonRpcError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/JsonRpcErrorCode'
          description: >-
            The error code — a negative integer identifying the failure. See
            `JsonRpcErrorCode` for the full list of values and meanings.
        message:
          type: string
          description: A human-readable description of what went wrong.
        original_request:
          type: object
          additionalProperties:
            description: Any type
          description: >-
            An echo of the request that failed — the full JSON-RPC frame you
            sent

            (`jsonrpc`, `id`, `method`, `params`). Always present.
        requester_nodeid:
          type: string
          description: >-
            The node that sent the failed request. Present only on some routing
            errors.
        requester_identity:
          type: string
          description: >-
            The identity of the requester. Present only on some routing errors;
            same value as `requester_nodeid`.
        responder_nodeid:
          type: string
          description: >-
            The node that was handling the request. Present only on some routing
            errors.
        responder_identity:
          type: string
          description: >-
            The identity of the responder. Present only on some routing errors;
            same value as `responder_nodeid`.
        last_hop_timeout:
          type: boolean
          description: >-
            `true` when the request timed out on its final hop inside
            SignalWire. Present only on some timeout errors.
      required:
        - code
        - message
        - original_request
      description: >-
        A JSON-RPC 2.0 error object, delivered on the `error` field of a
        `JsonRpcResponse` when

        a request fails at the protocol level (bad version, authentication,
        scope, params, or

        your project's connection limit). It replaces `result` — a frame carries
        one or the other, never both.
      title: JsonRpcError
    signalwire.connect_signalwireConnectResponse:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsSignalwireConnectMessagesSignalwireConnectResponseJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: The id of the request this responds to.
        result:
          $ref: '#/components/schemas/Signalwire.ConnectResult'
          description: The method result. Present when the request succeeded.
        error:
          $ref: '#/components/schemas/JsonRpcError'
          description: >-
            Present instead of `result` when the request failed at the protocol
            level.
      required:
        - jsonrpc
        - id
      description: >-
        A JSON-RPC response frame correlated to a request by `id`. On success
        the frame carries

        `result` (the method result). If the request fails at the protocol level
        — an

        incompatible version, failed authentication, insufficient scope, invalid
        params, or your

        project's connection limit — the frame carries `error` instead of
        `result`. Many

        method-level failures (for example most Calling failures) are reported
        the other way: a

        normal `result` whose own `code` is not `"200"`. Each method documents
        which form its

        failures take.


        An `error` returned for `signalwire.connect` is followed by the service
        closing the

        WebSocket; open a new connection to try again. The same happens when

        `signalwire.reauthenticate` sends credentials that are rejected, except
        for a

        Subscriber Access Token. Errors on any other request leave the
        connection open.
      title: signalwire.connect_signalwireConnectResponse
    ChannelsSignalwireConnectMessagesSignalwireConnectRequestJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsSignalwireConnectMessagesSignalwireConnectRequestJsonrpc
    ChannelsSignalwireConnectMessagesSignalwireConnectRequestMethod:
      type: string
      enum:
        - signalwire.connect
      description: The name of the JSON-RPC method being invoked.
      title: ChannelsSignalwireConnectMessagesSignalwireConnectRequestMethod
    Signalwire.JwtAuthentication:
      type: object
      properties:
        jwt_token:
          type: string
          description: >-
            The token that authenticates this client — a Subscriber Access Token
            (SAT) for Call Fabric, generated by your backend.
        project:
          type: string
          description: >-
            Your SignalWire Project ID. Required when `jwt_token` is a Relay JWT
            created with

            the Relay REST API; omit it for a Subscriber Access Token, Video
            room token, or

            Chat token.
      required:
        - jwt_token
      description: >-
        Client authentication, for browser and mobile apps. Send a `jwt_token`
        that your

        backend mints and hands to the client — for Call Fabric a **Subscriber
        Access Token

        (SAT)**; a Video room token or Chat token also works on its own. A Relay
        JWT created

        with the Relay REST API must be sent together with its `project`. Never
        ship a

        project API token to the browser.
      title: Signalwire.JwtAuthentication
    Signalwire.ClientVersion:
      type: object
      properties:
        major:
          type: integer
          description: >-
            Major version. Browser and Call Fabric clients send `4`, the highest
            the service accepts.
        minor:
          type: integer
          description: Minor version. Must be `0` — the service rejects any non-zero minor.
        revision:
          type: integer
          description: Revision. Browser and Call Fabric clients send `0`.
      required:
        - major
        - minor
        - revision
      description: >-
        The Relay protocol version a **client** connection speaks. Browser and
        Call Fabric

        clients send `4.0.0`. Call Fabric (`call.*`, `subscriber.*`) requires
        `major` `4`;

        lower versions are rejected with `-32001`. The service rejects any
        `major` above `4`

        and any non-zero `minor`.
      title: Signalwire.ClientVersion
    Signalwire.ClientConnectParams:
      type: object
      properties:
        authentication:
          $ref: '#/components/schemas/Signalwire.JwtAuthentication'
          description: >-
            Your client credential — a `jwt_token` / Subscriber Access Token
            (SAT).
        version:
          $ref: '#/components/schemas/Signalwire.ClientVersion'
          description: >-
            The Relay protocol version your client speaks. Browser and Call
            Fabric clients send `4.0.0`.
        agent:
          type: string
          description: >-
            A label identifying your SDK and application, for example
            `my-voice-app/1.0.0`.
        protocol:
          type: string
          description: >-
            The protocol identifier to resume. Provide this to rejoin a protocol
            you

            established earlier, when your project's permissions allow it.
        authorization_state:
          type: string
          description: >-
            Authorization state from an earlier `signalwire.authorization.state`
            event.

            Pass it back when reconnecting to restore your permissions and
            state. Treat it

            as an opaque token — store the value you received and return it
            unchanged. When

            you set this, you must also set `protocol`; the service rejects an

            `authorization_state` sent without a `protocol`.
        event_acks:
          type: boolean
          description: >-
            Accepted for compatibility but has no effect. Events are delivered
            as

            notifications, and the service does not wait for or read
            acknowledgements.
        contexts:
          type: array
          items:
            type: string
          description: >-
            Contexts to start receiving inbound events for as soon as you
            connect.
        dpop_token:
          type: string
          description: >-
            Optional proof-of-possession token that cryptographically binds this
            connection

            to your client. Only needed for advanced DPoP token-binding flows (a
            bound SAT);

            leave it unset otherwise.
      required:
        - authentication
        - version
      description: >-
        The parameters you send with `signalwire.connect` from a
        **browser/client** app:

        your `jwt_token` (a Subscriber Access Token for Call Fabric), protocol
        version

        (`4.0.0`), and any contexts to subscribe to.
      title: Signalwire.ClientConnectParams
    signalwire.connect_signalwireConnectRequest:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsSignalwireConnectMessagesSignalwireConnectRequestJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: Request id, echoed on the correlated response.
        method:
          $ref: >-
            #/components/schemas/ChannelsSignalwireConnectMessagesSignalwireConnectRequestMethod
          description: The name of the JSON-RPC method being invoked.
        params:
          $ref: '#/components/schemas/Signalwire.ClientConnectParams'
          description: The method's input parameters.
      required:
        - jsonrpc
        - id
        - method
        - params
      description: >-
        A JSON-RPC request frame. `Method` is the method name; `Params` is the
        method's input.
      title: signalwire.connect_signalwireConnectRequest

```