> ## Índice de la documentación
> Consulta el índice completo de la documentación en: https://developer.rhombus.com/llms.txt
> Úsalo para descubrir todas las páginas disponibles antes de seguir explorando.

# Claves de API y certificados

> Crea una clave de API de Rhombus, elige su rol, llama a la API con ella y usa una clave de certificado (mTLS): vencimiento, crear, rotar y renovar claves con la API, la CSR y la revocación.

> **Note**: Esta página se tradujo automáticamente. Si encuentras errores o tienes sugerencias, [escríbenos](mailto:support@rhombus.com).

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](https://console.rhombussystems.com/settings/integrations/api-tokens/), 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](https://console.eu.rhombussystems.com/settings/integrations/api-tokens/).
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](https://developer.rhombus.com/es/authentication/api-keys#claves-de-certificado-mtls)).
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](https://developer.rhombus.com/es/authentication/permissions).
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](https://developer.rhombus.com/es/authentication/api-keys#gestionar-claves-con-la-api).

## Llamar a la API con una clave

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

```bash cURL
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 '{}'
```

```python Python
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()
```

```javascript JavaScript
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](https://developer.rhombus.com/es/partner-api-calls)). 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](https://developer.rhombus.com/es/authentication/federated-tokens). 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`](https://developer.rhombus.com/api-reference/org-integrations-webservice/get-api-tokens)) 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`](https://developer.rhombus.com/api-reference/org-integrations-webservice/revoke-api-token)) 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](https://developer.rhombus.com/es/rate-limits) de tu organización.

Para reemplazar una clave sin tiempo de inactividad, consulta [Rotar una clave de API](https://developer.rhombus.com/es/authentication/permissions#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`:

| Acción                 | Claves de organización                                                                                                                                    | Claves de partner                                                                                                                                                       |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Crear                  | [`/api/integrations/org/submitApiTokenApplication`](https://developer.rhombus.com/api-reference/org-integrations-webservice/submit-api-token-application) | [`/api/partner/submitApiTokenApplication`](https://developer.rhombus.com/api-reference/partner-webservice/submit-api-token-application)                                 |
| Rotar                  | [`/api/integrations/org/rotateApiToken`](https://developer.rhombus.com/api-reference/org-integrations-webservice/rotate-api-token)                        | [`/api/partner/rotateApiToken`](https://developer.rhombus.com/api-reference/partner-webservice/rotate-api-token)                                                        |
| Renovar un certificado | [`/api/integrations/org/renewApiTokenCert`](https://developer.rhombus.com/api-reference/org-integrations-webservice/renew-api-token-certificate)          | [`/api/partner/renewApiTokenCert`](https://developer.rhombus.com/api-reference/partner-webservice/renew-api-token-certificate)                                          |
| Quién puede llamar     | Una sesión de la consola o de la app móvil, un access token de OAuth o una clave de API, cuyo rol incluya administración de la API                        | Una sesión de partner de la consola o de la app móvil, un access token de OAuth de partner o una clave de partner, cuyo rol de partner incluya administración de la API |

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](https://developer.rhombus.com/es/authentication/permissions#scopes-de-oauth)). El `submitApiTokenApplication` obsoleto, anterior a la ruta `/org/`, no acepta credenciales de API; usa los endpoints anteriores.

### Crear una clave

- **`displayName` (body, string, required)**: El nombre de la clave, que aparece en la consola y en el registro de auditoría.
- **`permissionGroupUuid` (body, string, required)**: El rol con el que actúa la clave: uno que tengas permitido asignar. Lista los roles con [`getPermissionGroups`](https://developer.rhombus.com/api-reference/permission-webservice/get-permission-groups).
- **`authType` (body, string, required)**: `API_TOKEN` para una clave simple, o `CERT` para una [clave de certificado](https://developer.rhombus.com/es/authentication/api-keys#claves-de-certificado-mtls).
- **`csr` (body, string)**: Obligatorio con `CERT`: la solicitud de firma de certificado (CSR) en PEM para el certificado de cliente de la clave.
- **`expiresAtMs` (body, integer)**: Cuándo deja de funcionar la clave, en milisegundos de época Unix. Obligatorio cuando quien llama es una clave de API.

```bash cURL
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}"
```

```python Python
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:

- **`apiKey` (string)**: La clave. Se devuelve una sola vez; guárdala de forma segura.
- **`tokenUuid` (string)**: El ID de la clave, que se usa para rotarla, renovarla o eliminarla.
- **`expiresAtMs` (integer)**: Cuándo vence la clave, si tiene vencimiento.
- **`cert` (string)**: Solo claves de certificado: el certificado de cliente firmado (PEM).
- **`certNotAfterMs` (integer)**: Solo claves de certificado: cuándo vence el certificado.

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.

- **`tokenUuid` (body, string, required)**: La clave que se va a reemplazar.
- **`overlapSec` (body, integer, default: 86400)**: Cuánto tiempo sigue funcionando la clave anterior, en segundos: un día de forma predeterminada, 2592000 (30 días) como máximo.
- **`csr` (body, string)**: Obligatorio al rotar una clave de certificado: una CSR para el certificado de la clave nueva.
- **`expiresAtMs` (body, integer)**: El vencimiento de la clave nueva, en milisegundos de época Unix. Obligatorio cuando quien llama es una clave de API, con los mismos límites que al crear una clave.

```bash cURL
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](https://developer.rhombus.com/es/authentication/permissions#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](https://developer.rhombus.com/es/authentication/federated-tokens).

### 1. Genera una clave privada y una CSR

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

```bash
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](https://developer.rhombus.com/es/authentication/api-keys#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:

```bash cURL
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 '{}'
```

```python Python
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={},
)
```

```javascript JavaScript (Node.js)
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](https://developer.rhombus.com/es/partner-api-calls).

### 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`):

- **`tokenUuid` (body, string)**: La clave de certificado que se va a renovar. Omítelo cuando una clave de certificado renueva su propio certificado.
- **`csr` (body, string, required)**: Una CSR para el certificado nuevo, creada como en el [paso 1](https://developer.rhombus.com/es/authentication/api-keys#1-genera-una-clave-privada-y-una-csr).

```bash cURL
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](https://developer.rhombus.com/es/authentication/api-keys#rotar-una-clave) 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](https://developer.rhombus.com/es/oauth-authentication). 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](https://developer.rhombus.com/es/partner-api-calls) llega a todas las organizaciones cliente que gestionas.
- **Navegadores, apps móviles y cámaras de tu LAN:** genera un [token federado](https://developer.rhombus.com/es/authentication/federated-tokens) de corta duración desde tu backend.