Relay (third-party cameras)

Authenticate third party camera

Authenticate a third party camera, effectively validating the credentials specified to be used for it.

POST/api/relay/authenticateThirdPartyCamera

Authorizations

x-auth-apikeystringheaderrequired

Your Rhombus API key. Must be accompanied by the x-auth-scheme header set to api-token (or partner-api-token for partner endpoints).

Authorizationstringheader

Instead of an API key, an OAuth access token: Bearer <token>, with the write scope.

OAuth explains tokens and scopes.

Headers

x-auth-schemeenum<string>headerdefault: api-token

Authentication scheme identifier. Use api-token or partner-api-token with the x-auth-apikey header, api or partner-api with x-auth-apikey plus a client certificate, api-oauth-token or partner-api-oauth-token with x-auth-access-token, and federated-token with x-auth-ft. A request with Authorization: Bearer <token> and no x-auth-scheme is treated as OAuth, and federated-token may also be sent as the x-auth-scheme and x-auth-ft query parameters.

Available options: api-token, api, api-oauth-token, federated-token, partner-api-token, partner-api, partner-api-oauth-token

x-auth-orgstring<RUUID>header

Client organization UUID (22-character RUUID), for partner credentials only. With it the call runs in that client organization with the partner support authority's role. Without it a partner credential runs as the partner organization, which outside the partner endpoints is deprecated (responses carry Deprecation and Sunset: Tue, 05 Jan 2027 00:00:00 GMT). A malformed value returns 400 INVALID_AUTH_ORG; a client organization the partner cannot access returns 403 PARTNER_CLIENT_ACCESS_DENIED.

Length: 22 to 22

Body

application/json · object

Request object for authenticating a third-party camera with RTSP URL.

locationUuidstring<RUUID> | nullbody

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

passwordstring | nullbody

Password to access the RTSP URL. This field MUST be non-empty if trySavedCredentials is false

Example: "password123"

rtspUrlstring | nullbody

The RTSP URL of the third-party camera. This RTSP URL should reference a stream that provides H.264 encoded video

Example: "rtsp://192.168.1.100:554/stream1"

thirdPartyCameraMacAddressstring | nullbody

The MAC address of the third-party camera this request is operating on

trySavedCredentialsboolean | nullbody

Whether the third-party credentials saved in the account should be used when trying to validate whether the provided RTSP URL is valid

Example: false

usernamestring | nullbody

Username to access the RTSP URL. This field MUST be non-empty if trySavedCredentials is false

Example: "admin"

bash

curl --request POST \
  --url 'https://api2.rhombussystems.com/api/relay/authenticateThirdPartyCamera' \
  --header 'x-auth-scheme: api-token' \
  --header 'x-auth-apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "locationUuid": "AAAAAAAAAAAAAAAAAAAAAA",
    "password": "password123",
    "rtspUrl": "rtsp://192.168.1.100:554/stream1",
    "thirdPartyCameraMacAddress": "<string>",
    "trySavedCredentials": false,
    "username": "admin"
  }'

import requests

url = "https://api2.rhombussystems.com/api/relay/authenticateThirdPartyCamera"
headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "locationUuid": "AAAAAAAAAAAAAAAAAAAAAA",
    "password": "password123",
    "rtspUrl": "rtsp://192.168.1.100:554/stream1",
    "thirdPartyCameraMacAddress": "<string>",
    "trySavedCredentials": False,
    "username": "admin"
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

const response = await fetch('https://api2.rhombussystems.com/api/relay/authenticateThirdPartyCamera', {
  method: 'POST',
  headers: {
    'x-auth-scheme': 'api-token',
    'x-auth-apikey': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "locationUuid": "AAAAAAAAAAAAAAAAAAAAAA",
    "password": "password123",
    "rtspUrl": "rtsp://192.168.1.100:554/stream1",
    "thirdPartyCameraMacAddress": "<string>",
    "trySavedCredentials": false,
    "username": "admin"
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);

console.log(await response.json());

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "locationUuid": "AAAAAAAAAAAAAAAAAAAAAA",
              "password": "password123",
              "rtspUrl": "rtsp://192.168.1.100:554/stream1",
              "thirdPartyCameraMacAddress": "<string>",
              "trySavedCredentials": false,
              "username": "admin"
            }
            """;
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api2.rhombussystems.com/api/relay/authenticateThirdPartyCamera"))
            .header("x-auth-scheme", "api-token")
            .header("x-auth-apikey", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

json

{
  "error": false,
  "errorCode": "<string>",
  "result": {
    "codec": "<string>",
    "createdOn": "2026-01-01T00:00:00Z",
    "ipAddress": "<string>",
    "lastVisibleMs": {
      "<key>": 0
    },
    "macAddress": "<string>",
    "manufacturer": "<string>",
    "model": "<string>",
    "name": "<string>",
    "onvifPassword": "<string>",
    "onvifProfileToken": "<string>",
    "onvifUsername": "<string>",
    "orgUuid": "AAAAAAAAAAAAAAAAAAAAAA",
    "password": "<string>",
    "rtspEndpoints": [
      {
        "audioSupported": true,
        "lastRtspUrlStatus": "GOOD",
        "lensRole": "VISIBLE",
        "onvifProfileToken": "<string>",
        "rtspUrl": "<string>",
        "source": "USER",
        "uuid": "AAAAAAAAAAAAAAAAAAAAAA"
      }
    ],
    "updatedOn": "2026-01-01T00:00:00Z",
    "username": "<string>"
  },
  "rtspUrlStatus": "GOOD"
}

Response

200 OK

application/json · object

Response object for authenticating a third-party camera with RTSP URL.

errorboolean | null

errorCodestring | null

Stable, machine-readable code for the failure (one of the ApiErrorCode catalog) when error is true. Branch on this, not on errorMsg.

errorMsgstring | null

resultobject

The imported (discovered) third-party camera. This field is populated only if the RTSP URL specified in the import resulted in creation of a new discovery or an addition of a RTSP URL to an existing discovery. It is null, if the RTSP URL already existed or if the import was not successful.

Show child attributes

codecstring | null

createdOnstring<date-time> | null

ipAddressstring | null

lastVisibleMsobject | null

macAddressstring | null

manufacturerstring | null

modelstring | null

namestring | null

onvifPasswordstring | null

onvifProfileTokenstring | null

onvifUsernamestring | null

orgUuidstring<RUUID> | null

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

passwordstring | null

rtspEndpointsobject[] | null

Show child attributes

audioSupportedboolean | null

lastRtspUrlStatusenum<string>

Status of the RTSP URL validation

Available options: UNKNOWN, NOT_REACHABLE, NOT_AUTHENTICATED, NOT_SUPPORTED, GOOD

lensRoleenum<string>

Available options: VISIBLE, THERMAL

onvifProfileTokenstring | null

rtspUrlstring | null

sourceenum<string>

Available options: USER, ONVIF

uuidstring<RUUID> | null

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

updatedOnstring<date-time> | null

usernamestring | null

rtspUrlStatusenum<string>

Status of the RTSP URL validation

Available options: UNKNOWN, NOT_REACHABLE, NOT_AUTHENTICATED, NOT_SUPPORTED, GOOD

warningMsgstring | null

Errors

Like every operation, this one can also answer with the standard error body (errorCode, errorMsg). Errors explains each status and how to retry.

400 Bad Request. errorCode is one of: BAD_REQUEST, VALIDATION_FAILED, MISSING_REQUIRED_FIELD, INVALID_JSON, INVALID_REQUEST_BODY, FEATURE_NOT_ENABLED, INVALID_AUTH_ORG, LOCATION_NOT_FOUND.
401 Unauthorized. errorCode is one of: UNAUTHENTICATED, INVALID_CREDENTIAL, CREDENTIAL_EXPIRED, CREDENTIAL_REVOKED, CERTIFICATE_MISMATCH.
403 Forbidden. errorCode is one of: FORBIDDEN, DOMAIN_NOT_ALLOWED, DEVICE_SCOPE_MISMATCH, ROLE_NOT_PERMITTED, FUNCTIONALITY_REQUIRED, PARTNER_FUNCTIONALITY_REQUIRED, PERMISSION_REQUIRED, PARTNER_CLIENT_ACCESS_DENIED, HARDWARE_NOT_AVAILABLE, HARDWARE_ALREADY_REGISTERED, PARTNER_PORTAL_NOT_ENABLED, MANAGED_BY_MSP, SUPER_ADMIN_RESTRICTED_BY_MSP, MSP_DESIGNATION_INVALID, NOT_MANAGED_CLIENT.
429 Too Many Requests. errorCode is one of: RATE_LIMITED.
500 Internal Server Error. errorCode is one of: INTERNAL_ERROR.
503 Service Unavailable. errorCode is one of: SERVICE_UNAVAILABLE.