> ## Í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.

# Autenticar medios y transmisiones

> Cómo autenticar instantáneas, fotogramas exactos, descargas de clips, transmisiones HLS, DASH y WebSocket en vivo y grabadas, enlaces de transmisión compartida y transmisiones LAN de Rhombus, desde servidores, apps nativas y navegadores.

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

Los medios (instantáneas, fotogramas, clips, video en vivo y grabado, audio) provienen de los hosts de medios, no de la API REST, y las URL que devuelve la API **no llevan ninguna credencial**. Tú agregas una a cada solicitud. Tres reglas cubren casi todo:

1. **Desde tu servidor o una app nativa**, envía tu clave de API como encabezados (`x-auth-scheme: api-token` y `x-auth-apikey`), o un access token de OAuth como `Authorization: Bearer <token>`.
2. **Desde un navegador** (un `<img>`, un `<video>`, un reproductor de JavaScript o un WebSocket), envía un [token federado](https://developer.rhombus.com/es/authentication/federated-tokens) como parámetros de consulta: `?x-auth-scheme=federated-token&x-auth-ft=<token>`. Las claves de API y los access tokens de OAuth no se pueden enviar en una URL.
3. **Las cámaras de tu red local** aceptan solo tokens federados. Es una decisión deliberada: en la red local, cada solicitud lleva un token de corta duración que puedes limitar a una cámara. Consulta [Streaming por LAN](https://developer.rhombus.com/es/implementations/lan-streaming).

> **Note**: **Dos WebSockets distintos.** El video y el audio en vivo se transmiten por URL de WebSocket por cámara que devuelve `getMediaUris`; siguen las reglas de esta página. El WebSocket de **eventos** en `ws.rhombussystems.com` entrega alertas y cambios de dispositivos; consulta [Autenticación de WebSocket](https://developer.rhombus.com/es/websocket/authentication).

## Hosts

| Qué                                          | Host de EE. UU.                                                                   | Notas                                                                                                          |
| -------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Instantáneas, fotogramas, descargas de clips | `media.rhombussystems.com`                                                        | UE: `media.eu.rhombussystems.com`                                                                              |
| Transmisiones en vivo y grabadas             | Hosts por cámara como `<id>.dash.rhombussystems.com`, que devuelve `getMediaUris` | Algunas solicitudes a `media.rhombussystems.com` redirigen (307) al host de la cámara; sigue las redirecciones |
| Cámaras en tu LAN                            | `<camera>.lan.rhombussystems.com:8000`                                            | DNS público para una dirección privada; usa el nombre de host, no la IP                                        |

Las credenciales están vinculadas a una región: una clave o un token de EE. UU. no funciona en hosts de la UE.

## Instantáneas y fotogramas exactos

La instantánea más reciente de una cámara:

```text
https://media.rhombussystems.com/media/{cameraUuid}/{mediaRegion}/snapshot.jpeg
```

`cameraUuid` y `mediaRegion` provienen de [`getMinimalCameraStateList`](https://developer.rhombus.com/api-reference/camera-webservice/get-minimal-camera-state-list).

```bash cURL (server)
curl "https://media.rhombussystems.com/media/CAMERA_UUID/MEDIA_REGION/snapshot.jpeg" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -o snapshot.jpeg
```

```bash cURL (OAuth)
curl "https://media.rhombussystems.com/media/CAMERA_UUID/MEDIA_REGION/snapshot.jpeg" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -o snapshot.jpeg
```

```html Browser
<img src="https://media.rhombussystems.com/media/CAMERA_UUID/MEDIA_REGION/snapshot.jpeg?x-auth-scheme=federated-token&x-auth-ft=TOKEN" />
```

Para un fotograma en un momento específico, llama a [`getExactFrameUri`](https://developer.rhombus.com/api-reference/video-webservice/get-exact-frame-uri) (marcas de tiempo en milisegundos). La URI que devuelve **no está firmada**: solicítala con los mismos encabezados o, en un navegador, agrégale los mismos parámetros de consulta.

## Descargas de clips guardados

Los clips guardados (de [`spliceV3`](https://developer.rhombus.com/api-reference/video-webservice/splice-v3) o de la consola) se descargan del host de medios según la región y el UUID del clip. Toma la región del `clipLocation` del clip:

```bash
curl "https://media.rhombussystems.com/media/metadata/{clipLocation.region}/{clipUuid}.mp4" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -o clip.mp4
```

Para reproducirlo en línea, usa en su lugar `/media/play/{region}/{clipUuid}.mp4` (admite solicitudes Range). El rol de la credencial necesita permiso para ver video guardado. Un token federado limitado a un dispositivo puede obtener un clip guardado solo cuando todas las cámaras del clip son el dispositivo del token.

## Video en vivo y grabado

[`POST /api/camera/getMediaUris`](https://developer.rhombus.com/api-reference/camera-webservice/get-camera-media-uris) devuelve las URL de transmisión de una cámara:

| Campo                                           | Formato                                    | Úsalo con                                                                                             |
| ----------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `wanLiveM3u8Uri`                                | HLS                                        | `<video>` de Safari, hls.js, AVPlayer, ExoPlayer, ffmpeg                                              |
| `wanLiveMpdUri`                                 | DASH                                       | dash.js                                                                                               |
| `wanLiveH264Uri`                                | H.264 por WebSocket (la latencia más baja) | Un decodificador propio, o el [React SDK](https://developer.rhombus.com/es/implementations/react-sdk) |
| `wanVodM3u8UriTemplate`, `wanVodMpdUriTemplate` | HLS / DASH grabado                         | Reemplaza `{START_TIME}` (tiempo Unix, en **segundos**) y `{DURATION}` (en **segundos**)              |
| Campos `lan…`                                   | Los mismos formatos en tu LAN              | Consulta [Streaming por LAN](https://developer.rhombus.com/es/implementations/lan-streaming)          |

Llama a `getMediaUris` con la credencial que usará tu reproductor y luego autentica cada formato como se indica a continuación.

### HLS

Agrega el token a la URL de la playlist. En los hosts de la nube, la playlist lleva los parámetros de consulta del token a cada URL de segmento, así que los reproductores no necesitan nada más:

```javascript
const url = `${wanLiveM3u8Uri}?x-auth-scheme=federated-token&x-auth-ft=${token}`;
if (video.canPlayType("application/vnd.apple.mpegurl")) {
  video.src = url; // Safari
} else {
  const hls = new Hls();
  hls.loadSource(url);
  hls.attachMedia(video);
}
```

Desde una app nativa o un servidor, envía en su lugar los encabezados de la clave de API o `Authorization: Bearer` en cada solicitud.

### DASH

Agrega el token a la URL del manifiesto. En los hosts de la nube, los manifiestos DASH en vivo y grabados (y los manifiestos de clips de alertas) llevan los parámetros de consulta del token a cada URL de segmento, así que una sola URL funciona en cualquier reproductor:

```javascript
const url = `${wanLiveMpdUri}?x-auth-scheme=federated-token&x-auth-ft=${encodeURIComponent(token)}`;
const player = dashjs.MediaPlayer().create();
player.initialize(video, url, true);
```

Solo los parámetros de consulta de tokens federados y de enlaces compartidos se llevan a los segmentos. Las claves de API y `x-auth-org` nunca se copian en las URL de segmento, así que un cliente de servidor o nativo envía sus encabezados en cada solicitud.

Para las transmisiones desde una cámara de tu LAN, agrega tú mismo el token a cada solicitud. Con dash.js 5, un interceptor de solicitudes lo hace, y no modifica ninguna URL que ya lleve el token:

```javascript
const auth = `x-auth-scheme=federated-token&x-auth-ft=${encodeURIComponent(token)}`;
const withAuth = (url) => (url.includes("x-auth-ft=") ? url : `${url}${url.includes("?") ? "&" : "?"}${auth}`);

const player = dashjs.MediaPlayer().create();
player.addRequestInterceptor((request) => {
  request.url = withAuth(request.url);
  return Promise.resolve(request);
});
player.initialize(video, lanLiveMpdUris[0], true);
```

### WebSocket (H.264 y audio)

En un navegador, pon el token en la URL; desde un servidor o una app nativa, también funcionan los encabezados, igual que un access token de OAuth en `Authorization: Bearer`:

```javascript
const ws = new WebSocket(`${wanLiveH264Uri}?x-auth-scheme=federated-token&x-auth-ft=${token}`);
ws.binaryType = "arraybuffer";
```

Un token generado con `domain` funciona aquí: los navegadores envían `Origin` en el handshake del WebSocket. Consulta [El campo domain](https://developer.rhombus.com/es/authentication/federated-tokens#el-campo-domain).

Los sockets de medios abiertos (video en vivo, audio bidireccional, robot y PTZ) se cierran con el código `1008` en un máximo de 60 segundos cuando se revoca su credencial o cambia su acceso. Con un token de OAuth, el audio bidireccional se verifica en cada mensaje, y enviar audio sin el scope `physical` cierra el socket con `1008` ([Scopes de OAuth](https://developer.rhombus.com/es/authentication/permissions#scopes-de-oauth)).

El [socket en vivo del robot](https://developer.rhombus.com/es/robots/live-socket) acepta claves de API, access tokens de OAuth y tokens federados de la misma forma.

## Claves de partner

Un partner que llama desde un servidor a los medios de una organización cliente envía su credencial de partner como encabezados (`x-auth-scheme: api-token` con `x-auth-apikey`, o `Authorization: Bearer` con un token de OAuth de partner) más `x-auth-org: <client org UUID>`. `x-auth-org` es solo un encabezado y nunca se copia en las URL de segmento. Para un navegador, genera un token federado para la organización cliente (envía `x-auth-org` al generarlo).

## Enlaces de transmisión compartida

[`createSharedLiveVideoStream`](https://developer.rhombus.com/api-reference/camera-webservice/create-shared-live-video-stream) crea un enlace al video en vivo de una cámara que funciona sin ninguna credencial de Rhombus:

- `sharedLiveVideoStreamUrl` abre una página de reproductor de Rhombus; insértala en un `<iframe>`.
- `sharedLiveM3U8StreamUrl` es una playlist HLS sin procesar para tu propio reproductor.

Cualquiera que tenga el enlace puede ver la transmisión, así que trátalo como una contraseña:

- **`expirationTimeSecs` es el tiempo Unix (en segundos) en que el enlace deja de funcionar**, no una duración. Si lo omites, el enlace nunca vence.
- Enlaces protegidos con contraseña ([`createProtectedSharedLiveVideoStream`](https://developer.rhombus.com/api-reference/camera-webservice/create-protected-shared-live-video-stream)): la página del reproductor pide la contraseña; para la URL HLS sin procesar, envía `Authorization: Basic <base64(":" + password)>` (con un nombre de usuario vacío). Una contraseña faltante o incorrecta devuelve 401 con `WWW-Authenticate: Basic`.
- Elimina el enlace compartido ([`deleteSharedLiveVideoStream`](https://developer.rhombus.com/api-reference/camera-webservice/delete-shared-live-video-stream)) para detenerlo de inmediato.

## Solución de problemas

| Síntoma                                                                      | Causa probable                                                                                                                                                                                                                        | Solución                                                                                                                                                                                                       |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 403 `DOMAIN_NOT_ALLOWED` en una URL de medios                                | El token se generó con un `domain` que no es el origen exacto de la página (esquema, host, puerto), o la solicitud no lleva `Origin` ni `Referer` (un servidor, un reproductor nativo, una página con `Referrer-Policy: no-referrer`) | Genera el token con el origen exacto de tu página, o sin `domain` para clientes fuera de un navegador                                                                                                          |
| 401 en una URL de medios                                                     | La credencial falta, está dañada, venció o fue revocada; `errorCode` indica cuál                                                                                                                                                      | Envía la credencial en cada solicitud o genera un token nuevo ([Cómo interpretar los errores de autenticación](https://developer.rhombus.com/es/authentication#cómo-interpretar-los-errores-de-autenticación)) |
| Un manifiesto DASH de la LAN carga, pero los segmentos fallan                | Las solicitudes de segmentos no llevan token                                                                                                                                                                                          | Agrégalo a cada solicitud (consulta [DASH](https://developer.rhombus.com/es/authentication/media#dash))                                                                                                        |
| Funciona en hosts de EE. UU. y falla en hosts de la UE                       | Las claves y los tokens están vinculados a una región                                                                                                                                                                                 | Genera el token en la misma región que la cámara                                                                                                                                                               |
| Un token limitado a un dispositivo falla en `api2`                           | Los tokens con `deviceUUid` solo funcionan para medios                                                                                                                                                                                | Usa un token no limitado a un dispositivo para las llamadas REST                                                                                                                                               |
| 403 con un token limitado a un dispositivo en un clip o un enlace compartido | El clip incluye otras cámaras, o la URL no nombra ningún dispositivo                                                                                                                                                                  | Genera un token no limitado a un dispositivo para esas solicitudes                                                                                                                                             |
| 403 en una descarga de clip                                                  | El rol no puede ver video guardado, o la región de la URL es incorrecta                                                                                                                                                               | Revisa el rol y `clipLocation`                                                                                                                                                                                 |
| Un WebSocket de medios se cierra con el código `1008`                        | Se revocó la credencial o cambió su acceso, o un token de OAuth sin `physical` envió audio bidireccional                                                                                                                              | Vuelve a conectarte con una credencial válida, o pide el scope `physical`                                                                                                                                      |
| Un enlace compartido dejó de funcionar                                       | `expirationTimeSecs` era una duración (un tiempo Unix ya pasado)                                                                                                                                                                      | Envía un tiempo Unix en segundos                                                                                                                                                                               |