Authentication

The Nomid MDM API uses API keys to authenticate requests. This guide explains how to obtain and use your API key.

Overview

API keys are used to authenticate all requests to the Nomid MDM API. Include your API key in the X-API-Key header with every request.

X-API-Key: nm_acme_a1b2c3d4e5f6...

Getting Your API Key

API keys are created and managed through the Nomid Portal. Follow these steps to create your first API key.

Prerequisites

  • A Nomid MDM account with administrator access
  • Access to the Company Settings in the Nomid Portal
  1. 1

    Log in to the Nomid Portal

    Open your browser and navigate to the Nomid Portal. Sign in with your administrator credentials.

  2. 2

    Navigate to Integrations

    Once logged in, go to the Company Settings section and select the Integrations tab.

  3. 3

    Click Create API Key

    Click the "Create API Key" button located in the top-right corner of the Integrations page.

  4. 4

    Enter a Name

    In the modal that appears, enter a descriptive name for your API key. This helps you identify the key later (e.g., "Power BI Integration" or "CRM Sync").

  5. 5

    Copy Your Key

    After clicking Create, your API key will be displayed. Click the copy button to copy it to your clipboard. The key will only be shown once!

API Key Format

API keys follow this format:

nm_{company}_{random_32_chars}
  • All keys start with 'nm_'
  • Company-specific prefix for identification
  • 32 random characters for security

Using Your API Key

Include the API key in the X-API-Key header with every request:

curl -X GET "https://api.nomid.tech/emm/api/v1/assets" \
  -H "X-API-Key: nm_acme_a1b2c3d4e5f6..."

API key permissions

Each key carries the permissions you choose when you create it. An endpoint returns 403 if the key lacks the permission it needs. The MCP server returns a tool error instead.

PermissionDescription
DEVICES_READList and read devices, the fleet summary and command history. Required by the GET /assets endpoints, the BI API and the MCP device read tools. GET /device-user-logins needs DEVICES_READ, like the other device reads.
POLICIES_READList and read policies. Required by GET /policies, GET /policies/POLICY_ID and the MCP policy tools.
DEVICES_COMMANDSend a command to one device: lock, lost mode, message, status report, location update, policy sync, reboot, shutdown, launch app, clear app data and change policy (which also needs POLICIES_READ). Opt-in, and never implied by another permission. It must be combined with DEVICES_READ. Required by the standard POST command endpoints and the MCP command tools. Reporting Device User logins and logouts (POST /device-user-logins and POST /device-user-logins/logout) needs DEVICES_COMMAND, the permission that sends device commands; a key only gets it together with DEVICES_READ. Device User sessions have no permission of their own. Device User sessions API
DEVICES_COMMAND_DESTRUCTIVERun destructive commands on one device: wipe, reset or change the screen lock, relinquish ownership and uninstall apps. They run immediately, with no approval step in the portal. Opt-in, separate from DEVICES_COMMAND, and it must be combined with DEVICES_READ. The company must also turn on destructive commands under AI agent access in the portal. Required by the destructive command endpoints and the MCP destructive command tools.
PROVISIONINGCreate provisioning QR codes for the company's policies. Every QR code carries a new enrollment token that expires after 24 hours. Opt-in, and it must be combined with POLICIES_READ. Only a portal user who is allowed to provision devices and has access to all policies can create a key with it. Required by POST /policies/POLICY_ID/provisioning-qr-codes and the MCP tool create_provisioning_qr_code. Provisioning QR codes API
EXPORT_READLegacy permission. No endpoint or tool checks it, and new keys can no longer be created with it.
POLICIES_WRITEAn API key with the POLICIES_WRITE permission (Policy changes), combined with POLICIES_READ. Only a portal user with permission to edit policies can create a key with POLICIES_WRITE. Required by the POST endpoints and the MCP policy change tools. Policy changes API
LIBRARY_MANAGELIBRARY_MANAGE is a sensitive, company-wide grant for APK uploads and app management. It does not grant policy assignment, device commands, provisioning or account operations. APK uploads API · Library apps API

Where to send the key

The REST API accepts the key only in the X-API-Key header. The MCP endpoint accepts either X-API-Key or Authorization: Bearer followed by the key.

MCP server guide

Rate limits and headers

The REST read endpoints do not apply a per-key limit in the Nomid application, but build your client to back off on 429 anyway. The MCP endpoint allows 60 requests per minute per key. Device commands, policy changes (each propose and apply call) and provisioning QR codes share a write limit of 10 requests per minute per key, over REST and MCP combined. A Sign in with Nomid connection has the same MCP and write limits, counted per connection.

An HTTP 429 response includes a Retry-After header with the seconds to wait. When an MCP command, policy change or provisioning tool call exceeds the write limit, the tool error text gives the seconds instead. The API does not set X-RateLimit-Limit, X-RateLimit-Remaining or X-RateLimit-Reset headers.

Security Best Practices

  • Never expose API keys in client-side code or public repositories
  • Rotate keys regularly and revoke unused keys
  • Store keys in environment variables, not in code
  • Use the minimum permissions necessary for your integration

Authentication Errors

The API returns specific error codes for authentication issues:

Status CodeDescription
401Missing or invalid API key
403API key doesn't have required permissions
429Rate limit exceeded

Choose Your Time

Loading...
Open booking calendar