Claves y alcances
La clave
Una clave es una persona en un espacio: actúa como quien la creó, solo en ese espacio, con un techo de rol y solo con los alcances que se le marcaron. No suma permisos: los permisos, los grupos, los topes y la auditoría son los del panel, y se revisan en cada pedido.
- Forma:
tv_live_<prefijo>_<secreto>. El prefijo (12 caracteres) identifica la clave y se ve en el panel; el secreto (48) se compara en tiempo constante. Del secreto queda solo el hash. - Dónde va: solo en
Authorization: Bearer. En la URL (?api_key=,?token=…) se rechaza con 400key_in_query: una URL queda en los logs de cualquier proxy. Si ya la mandaste así, rotala. - Dónde no va: en un navegador o en una app que alguien pueda abrir. Para mostrar video en una página, tu servidor pide la sesión y le pasa al navegador solo el token de mirar (ver Guías).
El rol
Se elige un rol máximo al crearla (administrador, miembro o solo mira) y vale el menor entre ese y el que tenga hoy quien la creó. Si a esa persona le bajan el rol, la clave baja con ella.
| Rol | Qué puede |
|---|---|
| Solo mira | Ver las cámaras de sus grupos. No mueve, no habla, no toma el control. |
| Miembro | Ver y operar las cámaras de sus grupos (mover, fotos, grabar, hablar, tomar el control). |
| Administrador | Todas las cámaras, configurarlas, el bucket, los webhooks y las automatizaciones. |
Alcances
Sin el alcance, la ruta contesta 403 missing_scope (con required_scope) aunque el rol alcance.
| Alcance | Qué deja |
|---|---|
cameras:read |
Lista, detalle y estado de las cámaras, y el resultado de los comandos |
cameras:write |
Alta, baja y rotar credenciales (además pide administrador) |
ptz |
Mover, frenar, inicio y posiciones (guardar y borrar posiciones pide administrador) |
live |
Abrir el video en vivo (WebRTC y HLS) |
talk |
Hablarle a la cámara |
snapshots |
Pedir fotos y verlas |
recordings |
Grabaciones, y prender o apagar la grabación (cambiarla pide administrador) |
storage |
El bucket del espacio (administrador) |
events |
Eventos de las cámaras |
webhooks |
Webhooks de salida (administrador) |
control |
Tomar el control de una cámara por unos minutos (préstamo de control) |
automations:read |
Ver las automatizaciones y sus ejecuciones (administrador) |
automations:write |
Prenderlas y apagarlas (administrador) |
automations:run |
Ejecutar las que tienen el disparador Manual (administrador) |
Marcá solo lo que la integración necesita: una clave que solo mira video no necesita ptz ni control.
Cuándo deja de andar
En el pedido siguiente:
| Pasa esto | Responde |
|---|---|
| Se revoca, desde el panel o la app | 401 key_revoked |
| Venció | 401 key_expired |
| Quien la creó sale del espacio (o lo sacan) | 401 key_revoked, y queda revocada aunque vuelva a entrar |
| Quien la creó está suspendido | 401 creator_suspended; vuelve si se reactiva |
| El espacio está suspendido | 403 space_suspended |
Si se pierde, no hay forma de recuperarla: se crea otra y se revoca la vieja. Una clave revocada suelta en el acto el control de las cámaras que tuviera.
Qué queda registrado
Todo pedido que cambia algo deja una fila api.call en la auditoría encadenada, con el id de la clave y actor: api:<nombre de la clave>. Lo mismo cada fila que el panel escriba durante el pedido (ver un video, bajar un archivo, cambiar la configuración), cada comando a la cámara (actor en GET /cameras/{id}/commands/{command}) y cada evento de la cámara que nazca del pedido. Las lecturas dejan como mucho una fila api.read por clave y ruta cada 5 minutos.
Cada respuesta trae X-Request-Id: con eso se encuentra el pedido en la auditoría.