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. 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. 2

    Navega a Integraciones

    Una vez dentro, ve a la sección Configuración de la Empresa y selecciona la pestaña Integraciones.

  3. 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. 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. 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.

PermisoDescripción
DEVICES_READListar 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_READListar y leer políticas. Requerido por GET /policies, GET /policies/POLICY_ID y las herramientas de políticas de MCP.
DEVICES_COMMANDEnviar 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_DESTRUCTIVEEjecute 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.
PROVISIONINGCrea 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_READPermiso heredado (legacy). Ningún endpoint ni herramienta lo comprueba, y ya no se pueden crear claves nuevas con él.
POLICIES_WRITEUna 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_MANAGELIBRARY_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.

Guía del servidor MCP

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 EstadoDescripción
401Clave API faltante o inválida
403La clave API no tiene los permisos requeridos
429Límite de velocidad excedido

Elija su horario

Cargando...
Abrir el calendario de reservas