Claves de API y certificados

Una clave de API es la credencial para el código que ejecutas en tus propios servidores. Pertenece a una organización, actúa con el rol que le asignes y funciona hasta que la eliminas o hasta su vencimiento (expiresAtMs), si lo tiene. Una clave puede ser un token de API simple, que se envía en un encabezado, o una clave de certificado, que además necesita un certificado de cliente TLS (mTLS).

Crear una clave de API

1. En la Consola de Rhombus, ve a Configuración → Integraciones y recursos para desarrolladores → Tokens de API y haz clic en Agregar clave de API. Las organizaciones de la UE usan console.eu.rhombussystems.com.
2. Escribe un Nombre que indique qué usa la clave (warehouse-door-sync). Aparece en el registro de auditoría.
3. Elige un Tipo de autenticación: Token de API, o Certificado para mTLS (consulta Claves de certificado).
4. Elige un Rol. La clave puede hacer exactamente lo que el rol permite, así que elige el rol más restringido que cubra el trabajo. Consulta Permisos y rotación de claves.
5. Copia la clave. Se muestra una sola vez.

Para crear claves necesitas un rol con administración de la API, y solo puedes darle a una clave un rol que tengas permitido asignar. Para crear claves desde código, consulta Gestionar claves con la API.

Llamar a la API con una clave

Envía el esquema y la clave como encabezados en cada solicitud:

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

import os
import requests

session = requests.Session()
session.headers.update({
    "x-auth-scheme": "api-token",
    "x-auth-apikey": os.environ["RHOMBUS_API_KEY"],
    "Content-Type": "application/json",
})

cameras = session.post(
    "https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList", json={}
).json()

const res = await fetch(
  "https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList",
  {
    method: "POST",
    headers: {
      "x-auth-scheme": "api-token",
      "x-auth-apikey": process.env.RHOMBUS_API_KEY,
      "Content-Type": "application/json",
    },
    body: "{}",
  },
);
const cameras = await res.json();

Los mismos encabezados funcionan en los hosts de medios y en el handshake del WebSocket de eventos. Las claves de partner también los usan, más x-auth-org para actuar en una organización cliente (consulta API para partners). La clave nunca se acepta como parámetro de consulta, así que no puede autenticar un <img>, un <video> ni un WebSocket del navegador; en esos casos, usa un token federado. Las cámaras de tu red local solo aceptan tokens federados.

Vigencia y revocación

• Vencimiento. Una clave puede tener una hora de vencimiento, expiresAtMs (milisegundos de época Unix). Una clave creada por otra clave de API siempre tiene una. Una vez pasada, las solicitudes con la clave reciben 401 CREDENTIAL_EXPIRED; la clave sigue apareciendo en las listas de claves (getApiTokens) hasta que la eliminas. Una clave sin expiresAtMs funciona hasta que la eliminas.
• La revocación surte efecto en un máximo de 60 segundos en todos los hosts. Esto se aplica a eliminar una clave (en la consola o con revokeApiToken) y a cambiar su rol. Las conexiones abiertas del WebSocket de eventos que usaban la clave reciben un frame ERROR de STOMP y se cierran con el código 1008; los sockets de medios abiertos (video en vivo, audio bidireccional, robot, PTZ) se cierran con 1008 dentro de los mismos 60 segundos.
• Eliminar una clave termina lo que creó: las claves que creó se eliminan con ella, y los tokens federados que generó dejan de funcionar.
• Las claves están vinculadas a una región. Una clave de una organización de EE. UU. devuelve 401 INVALID_CREDENTIAL en los hosts de la UE, y al revés.
• Sin ajustes de red ni de límites por clave. Las claves no tienen una lista de IP permitidas ni un límite de solicitudes propio; todas las claves consumen el límite de solicitudes de tu organización.

Para reemplazar una clave sin tiempo de inactividad, consulta Rotar una clave de API.

Gestionar claves con la API

Las claves se pueden crear, rotar y, en el caso de las claves de certificado, renovar con la API. Todos los endpoints son POST:

Cuando quien llama es una clave de API:

• expiresAtMs es obligatorio: como máximo 365 días a partir de ahora, y no después del vencimiento de la propia clave que llama.
• Una clave crea y rota claves solo en su propia organización. Una clave de partner que envía x-auth-org recibe 403.
• Una clave que crea se elimina cuando se elimina la clave que llama.
• Los tokens federados no pueden llamar a estos endpoints, ni tampoco las claves que usan los dispositivos y apps de Rhombus (claves de TV, teclado, quiosco, estación de puerta, ejecutable y chatbot): reciben 403.

Un access token de OAuth necesita los tres scopes (read, write y physical) para crear, rotar o renovar claves (Scopes de OAuth). El submitApiTokenApplication obsoleto, anterior a la ruta /org/, no acepta credenciales de API; usa los endpoints anteriores.

Crear una clave

EXPIRES_AT_MS=$(( ($(date +%s) + 90 * 86400) * 1000 ))  # dentro de 90 días

curl -X POST "https://api2.rhombussystems.com/api/integrations/org/submitApiTokenApplication" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"displayName\": \"warehouse-door-sync\", \"permissionGroupUuid\": \"$ROLE_UUID\", \"authType\": \"API_TOKEN\", \"expiresAtMs\": $EXPIRES_AT_MS}"

import os
import time
import requests

res = requests.post(
    "https://api2.rhombussystems.com/api/integrations/org/submitApiTokenApplication",
    headers={
        "x-auth-scheme": "api-token",
        "x-auth-apikey": os.environ["RHOMBUS_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "displayName": "warehouse-door-sync",
        "permissionGroupUuid": os.environ["ROLE_UUID"],
        "authType": "API_TOKEN",
        "expiresAtMs": int((time.time() + 90 * 86400) * 1000),  # dentro de 90 días
    },
)
res.raise_for_status()
data = res.json()
if data.get("error"):
    raise RuntimeError(data.get("errorMsg"))
api_key = data["apiKey"]  # se muestra una sola vez: guárdala como una contraseña

La respuesta contiene la clave nueva:

Una solicitud rechazada puede devolver HTTP 200 con "error": true y un errorMsg, así que revisa el cuerpo además del estado.

Rotar una clave

rotateApiToken emite una clave de reemplazo con el mismo rol y mantiene la clave anterior funcionando durante un período de superposición, para que puedas desplegar la clave nueva sin tiempo de inactividad.

curl -X POST "https://api2.rhombussystems.com/api/integrations/org/rotateApiToken" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"tokenUuid\": \"$OLD_TOKEN_UUID\", \"overlapSec\": 172800, \"expiresAtMs\": $(( ($(date +%s) + 90 * 86400) * 1000 ))}"

La respuesta incluye apiKey, tokenUuid y expiresAtMs de la clave nueva y, para las claves de certificado, cert y certNotAfterMs, más previousKeyExpiresAtMs: cuándo deja de funcionar la clave anterior. Despliega la clave nueva antes de ese momento. El procedimiento completo está en Rotar una clave de API.

Claves de certificado (mTLS)

Una clave de certificado agrega un certificado de cliente TLS a la clave de API. Las solicitudes se rechazan a menos que presenten tanto la clave como el certificado emitido para ella, así que una clave filtrada no basta por sí sola. Úsala cuando tu política de seguridad exija TLS mutuo para las credenciales de servicio.

Dónde funciona: solo en los hosts de la API REST api2.rhombussystems.com y api2.eu.rhombussystems.com, que pasan el TLS directamente a Rhombus para que se pueda verificar el certificado de cliente. Los hosts de medios, el WebSocket de eventos y las cámaras de tu LAN no aceptan claves de certificado; para ellos, usa una clave de API aparte o un token federado.

1. Genera una clave privada y una CSR

Genera la clave en la máquina que la va a usar y mantenla ahí:

openssl req -new -newkey rsa:2048 -nodes \
  -keyout rhombus-client.key \
  -out rhombus-client.csr \
  -subj "/CN=warehouse-door-sync"

Funcionan tanto las claves RSA de 2048 bits como las ECDSA P-256. Rhombus define el sujeto del certificado por su cuenta, así que el CN que elijas no importa. Rhombus verifica la firma de la CSR, que demuestra que tienes su clave privada; una CSR cuya firma no se puede verificar se rechaza. openssl req la firma por ti.

2. Crea la clave

En Agregar clave de API, elige Tipo de autenticación: Certificado, elige un rol y pega el contenido de rhombus-client.csr. Con la API, envía "authType": "CERT" y la CSR en csr (Crear una clave). Rhombus devuelve la clave de API y un certificado de cliente firmado. Guarda el certificado como rhombus-client.crt.

3. Llama a la API

Usa el esquema api, envía la clave en x-auth-apikey como de costumbre y presenta el certificado en el handshake TLS:

curl -X POST "https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList" \
  --cert rhombus-client.crt --key rhombus-client.key \
  -H "x-auth-scheme: api" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

import os
import requests

res = requests.post(
    "https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList",
    cert=("rhombus-client.crt", "rhombus-client.key"),
    headers={
        "x-auth-scheme": "api",
        "x-auth-apikey": os.environ["RHOMBUS_API_KEY"],
        "Content-Type": "application/json",
    },
    json={},
)

import { readFileSync } from "node:fs";
import https from "node:https";

const agent = new https.Agent({
  cert: readFileSync("rhombus-client.crt"),
  key: readFileSync("rhombus-client.key"),
});

const req = https.request(
  "https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList",
  {
    method: "POST",
    agent,
    headers: {
      "x-auth-scheme": "api",
      "x-auth-apikey": process.env.RHOMBUS_API_KEY,
      "Content-Type": "application/json",
    },
  },
  (res) => res.pipe(process.stdout),
);
req.end("{}");

Las claves de certificado de partner funcionan de la misma forma, con el esquema api (o su alias partner-api). Consulta API para partners.

Renovar un certificado

Los certificados duran 365 días. Antes de certNotAfterMs, obtén un certificado nuevo para la misma clave con renewApiTokenCert (claves de partner: /api/partner/renewApiTokenCert):

openssl req -new -newkey rsa:2048 -nodes \
  -keyout rhombus-client-new.key -out rhombus-client-new.csr -subj "/CN=warehouse-door-sync"

curl -X POST "https://api2.rhombussystems.com/api/integrations/org/renewApiTokenCert" \
  --cert rhombus-client.crt --key rhombus-client.key \
  -H "x-auth-scheme: api" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile csr rhombus-client-new.csr '{csr: $csr}')" \
  | jq -r .cert > rhombus-client-new.crt

La respuesta contiene cert y certNotAfterMs. La clave de API no cambia y no hay período de superposición, así que cambia el cliente al nuevo certificado y a la nueva clave privada en cuanto los recibas. Para cambiar también la clave, rótala con una CSR nueva.

Datos del certificado

• Validez: los certificados de desarrollador y de partner duran 365 días (certNotAfterMs). Renuévalos en el mismo lugar o rota la clave.
• TLS: TLS 1.2. Si tu red inspecciona el TLS, excluye los hosts api2; de lo contrario, el proxy elimina el certificado de cliente.
• Revocación: eliminar la clave revoca su certificado en un máximo de 60 segundos.
• Errores: un certificado que Rhombus no emitió hace fallar el propio handshake TLS (sin código de estado HTTP). Una clave de certificado enviada sin su certificado (por ejemplo, con x-auth-scheme: api-token), o con un certificado emitido para otra clave, devuelve 401 CERTIFICATE_MISMATCH (Client certificate does not match the api key).

Claves para otros tipos de acceso

• Los clientes autorizan tu app: usa Iniciar sesión con Rhombus. Una app de OAuth también puede crear una clave de API para el trabajo en segundo plano; la clave se elimina cuando el usuario revoca el acceso de la app.
• MSP y revendedores: una clave de API de partner llega a todas las organizaciones cliente que gestionas.
• Navegadores, apps móviles y cámaras de tu LAN: genera un token federado de corta duración desde tu backend.