Llamadas a la API de partner

Descripción general

Si eres un partner de Rhombus —un proveedor de servicios gestionados (MSP) o un revendedor que opera muchas organizaciones de clientes bajo una sola cuenta de partner—, tu clave de API funciona de forma distinta a la de una organización estándar. Una única clave de partner te permite:

• Gestionar tu conjunto de organizaciones cliente con endpoints de partner (/api/partner/...): listar clientes, registrar hardware, consultar licencias y emitir tokens de API.
• Acceder a cualquiera de esos clientes y llamar a endpoints a nivel de cliente (cámaras, control de acceso, sensores, usuarios — el resto de la API) como ese cliente, indicando la organización de destino en un solo encabezado de la solicitud.

Esta guía explica los dos tipos de llamadas, cómo se autentican las credenciales de partner y el encabezado x-auth-org que los une, de modo que un único conjunto de credenciales pueda operar en todas las organizaciones que gestionas.

Antes de empezar

Las URL base son las mismas que para cualquier otra llamada a la API de Rhombus; no hay un host de partner aparte. Usa las URL base de tu región (aquí se muestran las de EE. UU.; las organizaciones de la UE usan las variantes .eu.):

Dos tipos de llamadas

Cada solicitud que haces como partner es de uno de dos tipos. La diferencia está en la ruta del endpoint, y en si diriges la llamada a un cliente específico.

La idea clave: los endpoints de partner operan a nivel de partner; los endpoints a nivel de cliente operan dentro de una organización. Un partner accede a un cliente añadiendo el encabezado x-auth-org —explicado más abajo—. No existen "versiones de partner" de los endpoints de cliente; llamas al mismo endpoint /api/camera/... que usaría un cliente, solo que con credenciales de partner y el encabezado x-auth-org.

Autenticarse como partner

Las credenciales de partner usan los mismos esquemas y encabezados que cualquier otra credencial. api-token, api y api-oauth-token aceptan credenciales de partner, y partner-api-token, partner-api y partner-api-oauth-token se aceptan como alias de ellos. Con una clave de API de partner:

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

Crea una clave de API de partner en la Consola de Rhombus en Configuración → Gestión de API → Agregar clave de API.

Dirigir una llamada a una organización cliente

Para hacer una llamada a nivel de cliente en nombre de un cliente gestionado, añade el encabezado x-auth-org con el UUID de la organización de ese cliente:

Con este encabezado presente, Rhombus trata la solicitud como si proviniera de dentro de esa organización cliente. El servidor comprueba que el cliente haya concedido acceso a tu cuenta de partner (acceso de inicio de sesión, o gestión por tu MSP) y que esa concesión no haya expirado; si no es así, la solicitud se rechaza con 403 PARTNER_CLIENT_ACCESS_DENIED. Un valor que no es un UUID de organización válido se rechaza con 400 INVALID_AUTH_ORG. Dentro de la organización cliente, la llamada puede hacer lo que permita el rol que el cliente concedió a tu cuenta de partner.

• x-auth-org es solo un encabezado. Nunca se lee desde un parámetro de consulta.
• Significa lo mismo para cualquier credencial de partner: claves de API de partner, claves de certificado de partner y access tokens OAuth de partner.
• Un valor vacío cuenta como ausente.
• La Referencia de la API lo incluye en cada operación, y la CLI de Rhombus lo envía con su opción --partner-org.

Omite x-auth-org en los endpoints /api/partner/.... Los endpoints de partner operan a nivel de partner; enviar x-auth-org allí mueve la llamada a la organización cliente, así que falla o actúa sobre la organización equivocada.

Llamadas sin x-auth-org

Una credencial de partner que llama a un endpoint a nivel de cliente sin x-auth-org sigue funcionando, y actúa en tu organización de partner, pero la respuesta incluye dos encabezados:

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

A partir del 5 de enero de 2027, esas llamadas devuelven un error. Envía x-auth-org en cada llamada a nivel de cliente; los endpoints /api/partner/... no lo necesitan. El WebSocket de eventos ya rechaza un handshake de partner sin x-auth-org, con 403 PERMISSION_REQUIRED.

Ejemplos

Paso 1: Lista tus organizaciones cliente

Empieza con un endpoint de partner para descubrir las organizaciones que gestionas y sus UUID. POST /api/partner/getClientsV2 devuelve registros de cliente ligeros (nombre + UUID + conteo de dispositivos), ideal para resolver rápidamente el UUID de un cliente antes de actuar sobre él.

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)
	}
}

Una respuesta lista cada cliente gestionado, incluido el clientOrgUuid que pasarás como x-auth-org:

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

Paso 2: Llama a un endpoint a nivel de cliente como un cliente gestionado

Ahora usa un UUID de cliente del Paso 1 en el encabezado x-auth-org para llamar a un endpoint normal a nivel de cliente; aquí, listando las cámaras de un cliente con POST /api/camera/getMinimalCameraStateList. Ten en cuenta que no es un endpoint de partner; es el mismo endpoint de cámaras que usa cualquier organización, dirigido a tu cliente mediante el encabezado.

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,   # actuar como este cliente gestionado
    "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, // actuar como este cliente gestionado
  "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) // actuar como este cliente gestionado
	req.Header.Set("Content-Type", "application/json")

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

Si quitas el encabezado x-auth-org, la misma llamada apuntaría a tu organización de partner en lugar de al cliente, que normalmente no tiene cámaras propias, y la respuesta incluiría los encabezados Deprecation y Sunset descritos en Llamadas sin x-auth-org. El encabezado es lo que redirige la llamada hacia el cliente gestionado.

La CLI lo hace por ti

La CLI de Rhombus envuelve el mismo mecanismo tras una opción --partner-org, que acepta un UUID o un nombre de cliente y establece x-auth-org por ti:

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

# Por nombre de cliente (la CLI lo resuelve a un UUID con getClientsV2)
rhombus --partner-org "Acme Corporation" camera get-minimal-camera-state-list

Conexiones WebSocket

Las conexiones de partner en tiempo real usan las mismas credenciales. En el handshake del WebSocket, envía x-auth-apikey y x-auth-org como encabezados HTTP. x-auth-scheme puede ir en la cadena de consulta o en un encabezado. x-auth-org no se lee desde la cadena de consulta, y es obligatorio: un handshake de partner sin él se rechaza con 403 PERMISSION_REQUIRED. Los navegadores no permiten definir encabezados personalizados en el handshake de un WebSocket, así que conéctate desde un cliente del lado del servidor. Consulta Autenticación de WebSocket para ver el patrón completo.

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

Referencia de endpoints de partner

Estos endpoints /api/partner/... operan a nivel de partner y requieren una credencial de partner. Todos son POST. Consulta los esquemas completos de solicitud/respuesta en la Referencia de la API.

Claves de API de partner

Crea claves de partner en la consola en Configuración → Gestión de API, o con la API. Estos endpoints funcionan a nivel de partner, así que llámalos sin x-auth-org. Todos son POST:

• Quién puede llamarlos: una sesión de la consola o de la app móvil de partner, el access token OAuth de un usuario partner (con los tres scopes) o una clave de API de partner, cuyo rol de partner incluya la administración de la API. Los tokens federados no pueden.
• Cuando quien llama es una clave de API de partner, expiresAtMs es obligatorio: como máximo 365 días a partir de ahora, y no más tarde que la expiración de la propia clave que llama. La nueva clave se elimina cuando se elimina la clave que la creó. Una clave solo crea y rota claves en su propia organización, así que una clave de partner que envía x-auth-org a estos endpoints recibe 403.
• La rotación emite una clave con el mismo rol y mantiene la clave anterior funcionando durante overlapSec segundos; previousKeyExpiresAtMs indica cuándo deja de funcionar.
• La renovación conserva la misma clave y emite un certificado nuevo, sin solapamiento. Los certificados de partner duran 365 días, y se rechaza una CSR cuya firma no sea válida.
• Las claves expiradas reciben 401 CREDENTIAL_EXPIRED y siguen apareciendo en getApiTokens hasta que las revoques.

# Rota una clave de partner; la clave anterior sigue funcionando un día.
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}"

Gestionar claves con la API documenta los mismos campos para las claves de organización. Para emitir una clave de partner a partir del inicio de sesión de un usuario partner, consulta Iniciar sesión con Rhombus → Trabajar con cuentas partner.

Solución de problemas

Próximos pasos