Partner API Calls

Overview

If you're a Rhombus partner — a managed service provider (MSP) or reseller that operates many customer organizations under one partner account — your API key works differently from a standard organization key. A single partner key lets you:

• Manage your fleet of client organizations with partner endpoints (/api/partner/...) — list clients, register hardware, check licenses, and issue API tokens.
• Reach into any one of those clients and call client-level endpoints (cameras, access control, sensors, users — the rest of the API) as that client, by naming the target org in a single request header.

This guide explains the two kinds of calls, how partner credentials authenticate, and the x-auth-org header that ties them together so one set of credentials can operate across every organization you manage.

Before you begin

The base URLs are the same as for any other Rhombus API call — there is no separate partner host. Use your region's base URLs (US shown here; EU organizations use the .eu. variants):

Two kinds of calls

Every request you make as a partner is one of two kinds. The difference is the endpoint path — and whether you scope the call to a specific client.

The key idea: partner endpoints operate at the partner level, client-level endpoints operate inside one organization. A partner reaches into a client by adding the x-auth-org header — covered below. There are no "partner versions" of client endpoints; you call the same /api/camera/... endpoint a customer would, just with partner credentials and the x-auth-org header.

Authenticating as a partner

Partner credentials use the same schemes and headers as any other credential. api-token, api and api-oauth-token accept partner credentials, and partner-api-token, partner-api and partner-api-oauth-token are accepted as aliases for them. With a partner API key:

-H "x-auth-scheme: api-token" \
-H "x-auth-apikey: YOUR_PARTNER_API_KEY" \
-H "Content-Type: application/json"

Create a partner API key in the Rhombus Console under Settings → API Management → Add API Key.

Scoping a call to a client organization

To make a client-level call on behalf of a managed client, add the x-auth-org header set to that client's organization UUID:

With this header present, Rhombus treats the request as though it came from inside that client organization. The server checks that the client has granted your partner account access (login access, or management by your MSP) and that the grant hasn't expired; if not, the request is rejected with 403 PARTNER_CLIENT_ACCESS_DENIED. A value that isn't a valid organization UUID is rejected with 400 INVALID_AUTH_ORG. Inside the client org, the call can do what the role the client granted your partner account allows.

• x-auth-org is a header only. It's never read from a query parameter.
• It means the same for every partner credential: partner API keys, partner certificate keys and partner OAuth access tokens.
• A blank value counts as absent.
• The API Reference lists it on every operation, and the Rhombus CLI sets it for its --partner-org flag.

Omit x-auth-org on /api/partner/... endpoints. Partner endpoints operate at the partner level; sending x-auth-org there moves the call into the client org, so it fails or acts on the wrong org.

Calls without x-auth-org

A partner credential that calls a client-level endpoint without x-auth-org still works, and acts in your partner organization, but the response carries two headers:

Deprecation: true
Sunset: Tue, 05 Jan 2027 00:00:00 GMT

After January 5, 2027, those calls return an error. Send x-auth-org on every client-level call; the /api/partner/... endpoints don't need it. The event WebSocket already refuses a partner handshake without x-auth-org, with 403 PERMISSION_REQUIRED.

Examples

Step 1 — List your client organizations

Start with a partner endpoint to discover the orgs you manage and their UUIDs. POST /api/partner/getClientsV2 returns lightweight client records (name + UUID + device counts), ideal for quickly resolving a client UUID before acting on it.

curl -X POST https://api2.rhombussystems.com/api/partner/getClientsV2 \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

import requests

BASE_URL = "https://api2.rhombussystems.com"
headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_PARTNER_API_KEY",
    "Content-Type": "application/json",
}

resp = requests.post(f"{BASE_URL}/api/partner/getClientsV2", headers=headers, json={})
resp.raise_for_status()

for client in resp.json().get("clients", []):
    print(client["clientOrgName"], "->", client["clientOrgUuid"])

const BASE_URL = "https://api2.rhombussystems.com";
const headers = {
  "x-auth-scheme": "api-token",
  "x-auth-apikey": "YOUR_PARTNER_API_KEY",
  "Content-Type": "application/json",
};

const resp = await fetch(`${BASE_URL}/api/partner/getClientsV2`, {
  method: "POST",
  headers,
  body: JSON.stringify({}),
});
const data = await resp.json();
for (const client of data.clients ?? []) {
  console.log(`${client.clientOrgName} -> ${client.clientOrgUuid}`);
}

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api2.rhombussystems.com/api/partner/getClientsV2",
		bytes.NewBufferString("{}"))
	req.Header.Set("x-auth-scheme", "api-token")
	req.Header.Set("x-auth-apikey", "YOUR_PARTNER_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()

	var out struct {
		Clients []struct {
			ClientOrgName string `json:"clientOrgName"`
			ClientOrgUUID string `json:"clientOrgUuid"`
		} `json:"clients"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	for _, c := range out.Clients {
		fmt.Printf("%s -> %s\n", c.ClientOrgName, c.ClientOrgUUID)
	}
}

A response lists each managed client, including the clientOrgUuid you'll pass as x-auth-org:

{
  "clients": [
    {
      "clientOrgName": "Acme Corporation",
      "clientOrgUuid": "aB_cD1eF2gH3iJ4kL5mN6o",
      "totalCameras": 25,
      "totalLocations": 3
    },
    {
      "clientOrgName": "Beta Industries",
      "clientOrgUuid": "nO_pQ6rS7tU8vW9xY0zZ",
      "totalCameras": 12,
      "totalLocations": 1
    }
  ]
}

Step 2 — Call a client-level endpoint as a managed client

Now use a client UUID from Step 1 in the x-auth-org header to call a regular client-level endpoint — here, listing a client's cameras with POST /api/camera/getMinimalCameraStateList. Note this is not a partner endpoint; it's the same camera endpoint any organization uses, scoped to your client by the header.

curl -X POST https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_PARTNER_API_KEY" \
  -H "x-auth-org: aB_cD1eF2gH3iJ4kL5mN6o" \
  -H "Content-Type: application/json" \
  -d '{}'

import requests

BASE_URL = "https://api2.rhombussystems.com"
CLIENT_ORG_UUID = "aB_cD1eF2gH3iJ4kL5mN6o"

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_PARTNER_API_KEY",
    "x-auth-org": CLIENT_ORG_UUID,   # act as this managed client
    "Content-Type": "application/json",
}

resp = requests.post(
    f"{BASE_URL}/api/camera/getMinimalCameraStateList",
    headers=headers,
    json={},
)
resp.raise_for_status()
print(resp.json().get("cameraStates", []))

const BASE_URL = "https://api2.rhombussystems.com";
const CLIENT_ORG_UUID = "aB_cD1eF2gH3iJ4kL5mN6o";

const headers = {
  "x-auth-scheme": "api-token",
  "x-auth-apikey": "YOUR_PARTNER_API_KEY",
  "x-auth-org": CLIENT_ORG_UUID, // act as this managed client
  "Content-Type": "application/json",
};

const resp = await fetch(`${BASE_URL}/api/camera/getMinimalCameraStateList`, {
  method: "POST",
  headers,
  body: JSON.stringify({}),
});
console.log((await resp.json()).cameraStates);

package main

import (
	"bytes"
	"net/http"
)

func main() {
	clientOrgUUID := "aB_cD1eF2gH3iJ4kL5mN6o"

	req, _ := http.NewRequest("POST",
		"https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList",
		bytes.NewBufferString("{}"))
	req.Header.Set("x-auth-scheme", "api-token")
	req.Header.Set("x-auth-apikey", "YOUR_PARTNER_API_KEY")
	req.Header.Set("x-auth-org", clientOrgUUID) // act as this managed client
	req.Header.Set("Content-Type", "application/json")

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	// decode resp.Body...
}

Drop the x-auth-org header and the same call would target your partner organization instead of the client — which usually has no cameras of its own — and the response would carry the Deprecation and Sunset headers described in Calls without x-auth-org. The header is what redirects the call into the managed client.

The CLI does this for you

The Rhombus CLI wraps the same mechanism behind a --partner-org flag, accepting either a client UUID or name and setting x-auth-org for you:

# By UUID
rhombus --partner-org aB_cD1eF2gH3iJ4kL5mN6o camera get-minimal-camera-state-list

# By client name (the CLI resolves it to a UUID via getClientsV2)
rhombus --partner-org "Acme Corporation" camera get-minimal-camera-state-list

WebSocket connections

Real-time partner connections use the same credentials. On the WebSocket handshake, send x-auth-apikey and x-auth-org as HTTP headers. x-auth-scheme can go in the query string or a header. x-auth-org is not read from the query string, and it's required: a partner handshake without it is refused with 403 PERMISSION_REQUIRED. Browsers can't set custom headers on a WebSocket handshake, so connect from a server-side client. See WebSocket Authentication for the full pattern.

URL:     wss://ws.rhombussystems.com:8443/websocket?x-auth-scheme=api-token
Headers: x-auth-apikey: YOUR_PARTNER_API_KEY
         x-auth-org: aB_cD1eF2gH3iJ4kL5mN6o

Partner endpoint reference

These /api/partner/... endpoints operate at the partner level and require a partner credential. All are POST. Browse full request/response schemas in the API Reference.

Partner API keys

Create partner keys in the console under Settings → API Management, or with the API. These endpoints run at the partner level, so call them without x-auth-org. All are POST:

• Who can call them: a partner console or mobile app session, a partner user's OAuth access token (with all three scopes), or a partner API key, whose partner role includes API administration. Federated tokens can't.
• When the caller is a partner API key, expiresAtMs is required: at most 365 days from now, and no later than the calling key's own expiry. The new key is deleted when the calling key is deleted. A key creates and rotates keys only in its own organization, so a partner key that sends x-auth-org to these endpoints gets 403.
• Rotation issues a key with the same role and keeps the old key working for overlapSec seconds; previousKeyExpiresAtMs says when it stops.
• Renewal keeps the same key and issues a new certificate, with no overlap. Partner certificates last 365 days, and a CSR whose signature doesn't verify is rejected.
• Expired keys get 401 CREDENTIAL_EXPIRED and still appear in getApiTokens until you revoke them.

# Rotate a partner key; the old key keeps working for one day.
EXPIRES_AT_MS=$(( ($(date +%s) + 90 * 86400) * 1000 ))
curl -X POST "https://api2.rhombussystems.com/api/partner/rotateApiToken" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"tokenUuid\": \"OLD_TOKEN_UUID\", \"overlapSec\": 86400, \"expiresAtMs\": $EXPIRES_AT_MS}"

Manage keys with the API documents the same fields for organization keys. To mint a partner key from a partner user's sign-in, see Sign in with Rhombus → Working with partner accounts.

Troubleshooting

Next steps