Integraciones

Integrations

API RESTREST API

Observer RMM expone una API REST en JSON para que otros sistemas —un ITSM, una CMDB, una mesa de ayuda o su propio tablero— lean el inventario de equipos y, si se les autoriza, operen sobre la flota. Todo lo que hace la consola web pasa por esta misma API: aquí se documentan sus 184 rutas y 264 operaciones, y cómo autenticarse con una API key.

Observer RMM exposes a JSON REST API so other systems —an ITSM, a CMDB, a help desk or your own dashboard— can read the device inventory and, if authorized, act on the fleet. Everything the web console does goes through this same API: this page documents its 184 routes and 264 operations, and how to authenticate with an API key.

ContenidoContents

• Inicio rápido
• Cómo obtener una API key
• Autenticación y permisos
• Convenciones
• Leer el inventario (ITSM / CMDB)
• Ejemplos: curl, PowerShell y Python
• Buenas prácticas de seguridad
• Referencia de endpoints
• Rutas fuera del alcance de una API key

• Quick start
• How to get an API key
• Authentication and permissions
• Conventions
• Reading the inventory (ITSM / CMDB)
• Examples: curl, PowerShell and Python
• Security best practices
• Endpoint reference
• Routes outside the scope of an API key

Inicio rápidoQuick start

La API vive en el nombre de host API de su servidor Observer RMM —el mismo que usa la consola, normalmente https://api.su-dominio.cl— y se consume sólo por HTTPS. Cada solicitud lleva la clave en el encabezado X-API-KEY:

The API lives on the API hostname of your Observer RMM server —the same one the console uses, typically https://api.your-domain.com— and is served over HTTPS only. Every request carries the key in the X-API-KEY header:

curl -s https://api.su-dominio.cl/agents/?detail=false \
  -H "X-API-KEY: ABCDEFGHIJKLMNOPQRSTUVWXYZ012345" \
  -H "Accept: application/json"

La respuesta es un arreglo JSON con los equipos que el usuario dueño de la clave puede ver. El nombre de host de la API es el mismo al que se conecta el navegador al iniciar sesión en la consola.

The response is a JSON array with the devices the key's owner can see. The API hostname is the same one the browser connects to when you sign in to the console.

Cómo obtener una API keyHow to get an API key

Una API key actúa en nombre de un usuario de Observer RMM y hereda exactamente sus permisos. Por eso la práctica recomendada es crear un usuario de servicio dedicado a la integración, con un rol de sólo lectura, y generarle la clave. Lo hace un administrador desde la consola web del servidor RMM:

An API key acts on behalf of an Observer RMM user and inherits exactly that user's permissions. The recommended practice is therefore to create a dedicated service user for the integration, with a read-only role, and issue the key to it. An administrator does this from the RMM server's web console:

1. Cree un rol para la integración. Configuración → Gestor de permisos → nuevo rol (p. ej. «Integración ITSM»). Marque sólo lo que la integración necesita leer, por ejemplo Listar agentes, Listar clientes, Listar sitios y Listar software. En Clientes permitidos / Sitios permitidos puede acotar la visibilidad (vacío = todos).
2. Cree el usuario de servicio. Configuración → Administración de usuarios → nuevo usuario con ese rol. Active Denegar inicios de sesión al panel: el usuario existirá sólo para la API y nadie podrá entrar a la consola con él.
3. Genere la clave. Configuración → Configuración global → Claves de API → Agregar clave. Indique un Nombre descriptivo, elija el Usuario de servicio y, opcionalmente, una Expiración de la clave. El servidor genera una clave aleatoria de 32 caracteres, visible en la tabla de claves.
4. Entregue la clave por un canal seguro (gestor de contraseñas, no correo en claro) al equipo que opera la integración.

1. Create a role for the integration. Settings → Permissions Manager → new role (e.g. “ITSM integration”). Tick only what the integration needs to read, for example List Agents, List Clients, List Sites and List Software. Use Allowed Clients / Allowed Sites to narrow visibility (empty = all).
2. Create the service user. Settings → User Administration → new user with that role. Enable Deny Dashboard Logins: the user exists only for the API and nobody can sign in to the console with it.
3. Generate the key. Settings → Global Settings → API Keys → Add key. Enter a descriptive Name, pick the service User and, optionally, a Key Expiration. The server generates a random 32-character key, shown in the keys table.
4. Hand the key over through a secure channel (a password manager, not plain email) to the team running the integration.

Autenticación y permisosAuthentication and permissions

• Encabezado: X-API-KEY: <clave> en cada solicitud. No hay sesión, cookies ni renovación de tokens.
• Permisos: cada operación exige un permiso del rol del usuario dueño de la clave; la columna Permiso del rol de la referencia lo indica con el mismo nombre que muestra la consola.
• Visibilidad: los listados se recortan a los Clientes permitidos y Sitios permitidos del rol; un equipo fuera de ese alcance responde como si no existiera.
• Respuestas de error: 401 clave inválida, expirada o de un usuario inactivo · 403 el rol no tiene el permiso · 404 el recurso no existe o no es visible · 400 datos inválidos (el cuerpo trae el motivo en texto).
• Auditoría: las acciones hechas con la clave quedan en la auditoría a nombre del usuario de servicio.

• Header: X-API-KEY: <key> on every request. There are no sessions, cookies or token refreshes.
• Permissions: every operation requires a permission on the key owner's role; the Role permission column of the reference names it exactly as the console shows it.
• Visibility: listings are trimmed to the role's Allowed Clients and Allowed Sites; a device outside that scope behaves as if it did not exist.
• Error responses: 401 invalid or expired key, or inactive user · 403 the role lacks the permission · 404 the resource does not exist or is not visible · 400 invalid data (the body explains why, as text).
• Audit: actions performed with the key are recorded in the audit log under the service user.

ConvencionesConventions

• JSON de entrada y salida (Content-Type: application/json). Fechas en ISO 8601 y UTC.
• La barra final es obligatoria: /agents/, no /agents.
• Equipos: las rutas usan el agent_id (cadena larga única por equipo), no el id numérico. Obténgalo del listado GET /agents/.
• Consultas con filtros: algunos listados grandes (alertas, auditoría, historial de chequeos) se consultan con PATCH y los filtros en el cuerpo JSON; son lecturas, no modifican nada.
• Acciones sobre equipos (comandos, scripts, reinicios) se entregan al agente en línea; si el equipo está apagado la operación falla o queda como acción pendiente.

• JSON in and out (Content-Type: application/json). Dates in ISO 8601 and UTC.
• The trailing slash is required: /agents/, not /agents.
• Devices: routes use the agent_id (a long string unique per device), not the numeric id. Get it from the GET /agents/ listing.
• Filtered queries: some large listings (alerts, audit log, check history) are queried with PATCH and the filters in the JSON body; they are reads and change nothing.
• Device actions (commands, scripts, reboots) are delivered to the online agent; if the device is off the operation fails or is queued as a pending action.

Leer el inventario (ITSM / CMDB)Reading the inventory (ITSM / CMDB)

Una integración de inventario típica sólo necesita cuatro lecturas. Todas funcionan con el rol de sólo lectura descrito arriba.

A typical inventory integration needs only four reads. All of them work with the read-only role described above.

Campos de cada equipo en GET /agents/:

Fields of each device in GET /agents/:

Con ?detail=false la respuesta es liviana (identificación, sitio, tipo y configuración de alertas) y sirve para detectar altas y bajas sin traer el inventario completo.

With ?detail=false the response is lightweight (identity, site, type and alert settings), useful for detecting additions and removals without pulling the full inventory.

Ejemplos: curl, PowerShell y PythonExamples: curl, PowerShell and Python

curl

# Equipos de un cliente / Devices of one client
curl -s "https://api.su-dominio.cl/agents/?client=3" -H "X-API-KEY: $OBSERVER_API_KEY"

# Ficha de un equipo / One device's record
curl -s "https://api.su-dominio.cl/agents/{agent_id}/" -H "X-API-KEY: $OBSERVER_API_KEY"

PowerShell

$h = @{ "X-API-KEY" = $env:OBSERVER_API_KEY }
$agents = Invoke-RestMethod -Uri "https://api.su-dominio.cl/agents/" -Headers $h
$agents | Select-Object hostname, serial_number, operating_system, client_name, site_name, status |
  Export-Csv inventario.csv -NoTypeInformation -Encoding UTF8

Python

import os, requests

API = "https://api.su-dominio.cl"
s = requests.Session()
s.headers.update({"X-API-KEY": os.environ["OBSERVER_API_KEY"]})

for a in s.get(f"{API}/agents/", timeout=60).json():
    sw = s.get(f"{API}/software/{a['agent_id']}/", timeout=60).json()
    print(a["hostname"], a["serial_number"], a["status"], len(sw.get("software", []) if sw else []))

Buenas prácticas de seguridadSecurity best practices

• Mínimo privilegio: una integración de inventario no necesita permisos de comandos, scripts, reinicios, registro ni borrado. Si nunca los tiene, una clave filtrada no puede operar la flota.
• Nunca asocie la clave a un superusuario: un superusuario tiene todos los permisos y la clave también.
• Una clave por integración, con nombre que la identifique, para poder revocarla sin afectar a las demás.
• Expiración y rotación: fije una expiración y rote la clave periódicamente; guárdela en un gestor de secretos, nunca en el código.
• Restrinja el origen: si el ITSM tiene IP fija, pídale a su administrador que limite el acceso a la API a esa IP en el proxy o firewall.
• Operaciones destructivas (borrado remoto, desinstalación de agentes, modo perdido) exigen permisos propios, que ningún rol de integración debería tener.

• Least privilege: an inventory integration needs no command, script, reboot, registry or wipe permissions. If it never has them, a leaked key cannot operate the fleet.
• Never tie the key to a superuser: a superuser has every permission, and so does its key.
• One key per integration, with a name that identifies it, so it can be revoked without affecting the others.
• Expiration and rotation: set an expiration and rotate the key periodically; keep it in a secrets manager, never in code.
• Restrict the source: if the ITSM has a fixed IP, ask your administrator to limit API access to that IP at the proxy or firewall.
• Destructive operations (remote wipe, agent uninstall, lost mode) require their own permissions, which no integration role should have.

Referencia de endpointsEndpoint reference

Todas las rutas son relativas al nombre de host de la API. Las marcadas «uso de la consola» existen para la interfaz web y no son útiles para integraciones.

All paths are relative to the API hostname. Those marked “console use” exist for the web interface and are not useful for integrations.

• Agentes (equipos)
• Clientes y sitios
• Software instalado
• Windows Update
• Servicios de Windows
• Chequeos
• Tareas automatizadas
• Políticas de automatización
• Alertas
• Scripts
• Registros y acciones pendientes
• Configuración y utilidades
• Usuarios, roles y claves de API
• Borrado seguro y recuperación de archivos
• Reportería

• Agents (devices)
• Clients and sites
• Installed software
• Windows Update
• Windows services
• Checks
• Automated tasks
• Automation policies
• Alerts
• Scripts
• Logs and pending actions
• Settings and utilities
• Users, roles and API keys
• Secure erase and file retrieval
• Reporting

Agentes (equipos)Agents (devices)

Inventario y acciones sobre cada equipo administrado. El identificador de ruta es el agent_id (cadena larga), no el id numérico.

Inventory and actions on each managed device. The path identifier is the agent_id (long string), not the numeric id.

Clientes y sitiosClients and sites

La jerarquía organizacional: cada equipo pertenece a un sitio y cada sitio a un cliente.

The organizational hierarchy: every device belongs to a site and every site to a client.

Software instaladoInstalled software

Inventario de software por equipo y acciones de instalación o desinstalación.

Per-device software inventory and install/uninstall actions.

Windows UpdateWindows Update

Parches de Windows detectados por equipo, su aprobación e instalación.

Windows patches detected per device, their approval and installation.

Servicios de WindowsWindows services

Consulta y control de servicios de Windows de un equipo.

Query and control Windows services on a device.

ChequeosChecks

Chequeos de monitoreo (disco, CPU, memoria, servicios, scripts, ping, eventos) y su historial.

Monitoring checks (disk, CPU, memory, services, scripts, ping, events) and their history.

Tareas automatizadasAutomated tasks

Tareas programadas que ejecutan scripts u otras acciones en los equipos.

Scheduled tasks that run scripts or other actions on devices.

Políticas de automatizaciónAutomation policies

Políticas que agrupan chequeos, tareas y parches y se aplican a clientes, sitios o equipos.

Policies that bundle checks, tasks and patching and apply to clients, sites or devices.

AlertasAlerts

Alertas generadas por chequeos, tareas y disponibilidad, y sus plantillas.

Alerts raised by checks, tasks and availability, and their templates.

ScriptsScripts

Biblioteca de scripts y fragmentos reutilizables.

Library of scripts and reusable snippets.

Registros y acciones pendientesLogs and pending actions

Auditoría, registro de depuración y acciones en cola hacia los agentes.

Audit trail, debug log and actions queued for agents.

Configuración y utilidadesSettings and utilities

Configuración global, campos personalizados, almacén de claves, acciones URL y utilidades del servidor.

Global settings, custom fields, key store, URL actions and server utilities.

Usuarios, roles y claves de APIUsers, roles and API keys

Administración de usuarios, roles de permisos, sesiones y claves de API.

Administration of users, permission roles, sessions and API keys.

Borrado seguro y recuperación de archivosSecure erase and file retrieval

Órdenes de borrado remoto, certificados de borrado, recepción de activos y recuperación de archivos. Acciones destructivas: requieren permisos específicos y confirmación.

Remote wipe orders, erase certificates, asset intake and file retrieval. Destructive actions: they require specific permissions and confirmation.

ReporteríaReporting

Plantillas de reporte, consultas de datos, programaciones, historial y recursos.

Report templates, data queries, schedules, history and assets.

Rutas fuera del alcance de una API keyRoutes outside the scope of an API key

El inicio de sesión de la consola (/v2/login/, /logout/), el canal de los agentes (/api/v3/, /api/v4/) y los WebSockets son protocolos internos del producto y no se usan con API key. Además:

Console sign-in (/v2/login/, /logout/), the agent channel (/api/v3/, /api/v4/) and WebSockets are internal product protocols and are not used with an API key. Also: