Autenticación
La API de Nomid MDM usa claves API para autenticar solicitudes. Esta guía explica cómo obtener y usar tu clave API.
Descripción General
Las claves API se usan para autenticar todas las solicitudes a la API de Nomid MDM. Incluye tu clave API en el encabezado X-API-Key con cada solicitud.
X-API-Key: nm_acme_a1b2c3d4e5f6... Obtener Tu Clave API
Las claves API se crean y gestionan a través del Portal de Nomid. Sigue estos pasos para crear tu primera clave API.
Requisitos Previos
- Una cuenta de Nomid MDM con acceso de administrador
- Acceso a la Configuración de la Empresa en el Portal de Nomid
- 1
Inicia Sesión en el Portal de Nomid
Abre tu navegador y accede al Portal de Nomid. Inicia sesión con tus credenciales de administrador.
- 2
Navega a Integraciones
Una vez dentro, ve a la sección Configuración de la Empresa y selecciona la pestaña Integraciones.
- 3
Haz Clic en Crear Clave API
Haz clic en el botón "Crear Clave API" ubicado en la esquina superior derecha de la página de Integraciones.
- 4
Ingresa un Nombre
En el modal que aparece, ingresa un nombre descriptivo para tu clave API. Esto te ayuda a identificar la clave después (ej.: "Integración Power BI" o "Sincronización CRM").
- 5
Copia Tu Clave
Después de hacer clic en Crear, tu clave API será mostrada. Haz clic en el botón copiar para copiarla al portapapeles. ¡La clave solo se mostrará una vez!
Formato de Clave API
Las claves API siguen este formato:
nm_{company}_{random_32_chars} - Todas las claves comienzan con 'nm_'
- Prefijo específico de la empresa para identificación
- 32 caracteres aleatorios para seguridad
Usando Tu Clave API
Incluye la clave API en el encabezado X-API-Key con cada solicitud:
curl -X GET "https://api.nomid.tech/emm/api/v1/assets" \
-H "X-API-Key: nm_acme_a1b2c3d4e5f6..." Permisos de clave de API
Cada clave incluye los permisos que elija al crearla. Un endpoint devuelve 403 si la clave carece del permiso necesario. El servidor MCP devuelve un error de herramienta en su lugar.
| Permiso | Descripción |
|---|---|
| DEVICES_READ | Listar y leer dispositivos, el resumen de la flota y el historial de comandos. Requerido por los endpoints GET /assets, la API de BI y las herramientas de lectura de dispositivos de MCP. GET /device-user-logins requiere DEVICES_READ, al igual que las demás lecturas de dispositivos. |
| POLICIES_READ | Listar y leer políticas. Requerido por GET /policies, GET /policies/POLICY_ID y las herramientas de políticas de MCP. |
| DEVICES_COMMAND | Enviar un comando a un dispositivo: bloqueo, modo perdido, mensaje, informe de estado, actualización de ubicación, sincronización de políticas, reinicio, apagado, iniciar aplicación, borrar datos de la aplicación y cambiar política (que también necesita POLICIES_READ). Requiere consentimiento explícito (opt-in) y nunca está implícito en otro permiso. Debe combinarse con DEVICES_READ. Requerido por los endpoints de comandos POST estándar y las herramientas de comandos de MCP. Reportar inicios y cierres de sesión de usuarios de dispositivos (POST /device-user-logins y POST /device-user-logins/logout) requiere DEVICES_COMMAND, el permiso que envía comandos a los dispositivos; una clave solo lo obtiene junto con DEVICES_READ. Las sesiones de usuarios de dispositivos no tienen un permiso propio. API de sesiones de usuarios de dispositivos |
| DEVICES_COMMAND_DESTRUCTIVE | Ejecute comandos destructivos en un dispositivo: borrar, restablecer o cambiar el bloqueo de pantalla, renunciar a la propiedad y desinstalar aplicaciones. Se ejecutan de inmediato, sin ningún paso de aprobación en el portal. Es opcional (opt-in), independiente de DEVICES_COMMAND, y debe combinarse con DEVICES_READ. La empresa también debe habilitar los comandos destructivos en el acceso de agentes de IA en el portal. Requerido por los endpoints de comandos destructivos y las herramientas de comandos destructivos de MCP. |
| PROVISIONING | Crea códigos QR de aprovisionamiento para las políticas de la empresa. Cada código QR contiene un nuevo token de inscripción que caduca después de 24 horas. Opcional (opt-in), y debe combinarse con POLICIES_READ. Solo un usuario del portal que tenga permiso para aprovisionar dispositivos y tenga acceso a todas las políticas puede crear una clave con él. Requerido por POST /policies/POLICY_ID/provisioning-qr-codes y la herramienta MCP create_provisioning_qr_code. API de códigos QR de aprovisionamiento |
| EXPORT_READ | Permiso heredado (legacy). Ningún endpoint ni herramienta lo comprueba, y ya no se pueden crear claves nuevas con él. |
| POLICIES_WRITE | Una clave de API con el permiso POLICIES_WRITE (Cambios de política), combinado con POLICIES_READ. Solo un usuario del portal con permiso para editar políticas puede crear una clave con POLICIES_WRITE. Requerido por los endpoints POST y las herramientas de cambio de políticas de MCP. API de cambios de políticas |
| LIBRARY_MANAGE | LIBRARY_MANAGE es un permiso sensible, a nivel de toda la empresa, para las cargas de APK y la administración de aplicaciones. No concede la asignación de políticas, comandos de dispositivo, aprovisionamiento ni operaciones de la cuenta. API de cargas de APK · API de aplicaciones de la biblioteca |
Dónde enviar la clave
La API REST solo acepta la clave en el encabezado X-API-Key. El endpoint de MCP acepta tanto X-API-Key como Authorization: Bearer seguido de la clave.
Límites de velocidad y encabezados
Los endpoints de lectura REST no aplican un límite por clave en la aplicación Nomid, pero de todos modos diseñe su cliente para aplicar una espera exponencial (backoff) ante un 429. El endpoint de MCP permite 60 solicitudes por minuto por clave. Los comandos de dispositivo, los cambios de políticas (cada llamada propose y apply) y los códigos QR de aprovisionamiento comparten un límite de escritura de 10 solicitudes por minuto por clave, sumando REST y MCP. Una conexión de Sign in with Nomid tiene los mismos límites de MCP y de escritura, contabilizados por conexión.
Una respuesta HTTP 429 incluye un encabezado Retry-After con los segundos a esperar. Cuando una llamada de comando MCP, cambio de política o herramienta de aprovisionamiento supera el límite de escritura, el texto de error de la herramienta indica los segundos en su lugar. La API no establece los encabezados X-RateLimit-Limit, X-RateLimit-Remaining ni X-RateLimit-Reset.
Mejores Prácticas de Seguridad
- Nunca expongas claves API en código del lado del cliente o repositorios públicos
- Rota las claves regularmente y revoca las claves no utilizadas
- Almacena las claves en variables de entorno, no en el código
- Usa los permisos mínimos necesarios para tu integración
Errores de Autenticación
La API devuelve códigos de error específicos para problemas de autenticación:
| Código de Estado | Descripción |
|---|---|
| 401 | Clave API faltante o inválida |
| 403 | La clave API no tiene los permisos requeridos |
| 429 | Límite de velocidad excedido |