HTTP Protocol

The HTTP protocol defines how peers initiate communication with the Nabto WebRTC Signaling service.

All HTTP requests must be sent to the base URL of the Nabto WebRTC Signaling service. The exact endpoint structure is stable and documented in the sections below.

The protocol specification is only relevant as background information or if you want to make your own Nabto WebRTC Signaling protocol implementation, e.g. for a currently unsupported target platform or app framework. For most applications, the standard implementations provided by Nabto through the available SDKs are sufficient - see the Applications guide.

Authorization

HTTP requests can be authorized using a Bearer token in an Authorization header. A Websocket connection created based on an authorized HTTP request will also be authorized. The token must be signed with a private key for which the public key is configured in the Nabto Cloud Console. The public key is configured on the device page for device and on the product page for clients.

The token is a JWT of the format described in the Central Authorization guide.

Device (Camera) Connect Request

Request to allow a device to open a Websocket connection. On success, the response will contain a signaling URL which must be used when opening the Websocket connection.

HTTP Request

POST /v1/device/connect

Headers

Content-Type: application/json
Authorization: Bearer <TOKEN>

Request body

{
    deviceId: string,
    productId: string,
}

Response body

{
    signalingUrl: string
}

Client Connect Request

Request to allow a client to open a Websocket connection. If the Authorization header is provided and validated successfully, all messages relayed on the resulting Websocket connection will be marked as Authorized by the Signaling service. This allows the device to make authorization decisions based on central authorization.

On success, the response contains a signaling URL, a deviceOnline boolean and a channel ID. The signaling URL must be used when opening the Websocket connection. The channel ID must be used in each signaling message sent on the Websocket. The deviceOnline boolean will be true if the device is currently connected to the backend.

This allows the client to open a Websocket connection to the Signaling service even if the device is not currently connected. Letting the client have a Websocket connection open when the device is not connected allows more flexibility if the device reconnects to the Signaling service or is expected to connect momentarily.

HTTP Request

POST /v1/client/connect

Headers

Content-Type: application/json

Optional headers

Authorization: Bearer <TOKEN>

Request body

{
    deviceId: string,
    productId: string,
}

Response body

{
    signalingUrl: string,
    deviceOnline: boolean,
    channelId: string,
}

ICE Servers Request

Request ICE server configurations from the service. If the optional Authorization header is not provided, the response will only contain STUN servers. If the header is provided, the response will also contain TURN servers for relay in case network conditions do not allow WebRTC to establish a peer-to-peer connection.

HTTP Request

POST /v1/ice-servers

Headers

Content-Type: application/json

Optional headers

Authorization: Bearer <TOKEN>

Request body

{
    deviceId: string,
    productId: string,
}

Response body

{
    iceServers: {
        username?: string,
        credential?: string,
        urls: string[],
        }[],
}

HTTP Error Codes

The HTTP calls described in the previous sections can return non 200 status codes. Sometimes they come with a json body. The json body will have a string explaining what caused the error.

  • 200: OK
  • 400: If the request is not understood
  • 401: If the token used in the request is not valid
  • 403: If a valid token is used but it does not give access to the resource in question
  • 404: If the resource does not exists, e.g. if the productId or deviceId is not known
  • 429: If the service receives too many requests and asks the device to wait into the future to make more requests
  • 503: Service is currently unavailable
  • 5xx: If an unspecified service error happened

If the HTTP response returns 429 or 503 with a Retry-After header and the HTTP client wants to make an automatic retry, the HTTP client shall honor the Retry-After time but not a date. If a date is returned the HTTP client can choose to ignore it. This keeps the HTTP response parsing code simple.

Error format

{
  message: string, /* A message describing the error message. */
  code?: string /* An optional code describing the specific error condition. */
}

The following error codes are defined:

  • PRODUCT_ID_NOT_FOUND: If the product id in the request is not found.
  • DEVICE_ID_NOT_FOUND: If the device id in the request is not found.