Uwierzytelnianie

Nomid MDM API wykorzystuje klucze API do uwierzytelniania żądań. Ten przewodnik wyjaśnia, jak uzyskać i używać swojego klucza API.

Przegląd

Klucze API służą do uwierzytelniania wszystkich żądań do Nomid MDM API. Dołącz swój klucz API w nagłówku X-API-Key do każdego żądania.

X-API-Key: nm_acme_a1b2c3d4e5f6...

Uzyskiwanie klucza API

Klucze API są tworzone i zarządzane za pośrednictwem Portalu Nomid. Wykonaj poniższe kroki, aby utworzyć swój pierwszy klucz API.

Wymagania wstępne

  • Konto Nomid MDM z dostępem administratora
  • Dostęp do Ustawień Firmy w Portalu Nomid
  1. 1

    Zaloguj się do Portalu Nomid

    Otwórz przeglądarkę i przejdź do Portalu Nomid. Zaloguj się przy użyciu swoich danych administratora.

  2. 2

    Przejdź do Integracji

    Po zalogowaniu przejdź do sekcji Ustawienia Firmy i wybierz zakładkę Integracje.

  3. 3

    Kliknij Utwórz klucz API

    Kliknij przycisk "Utwórz klucz API" znajdujący się w prawym górnym rogu strony Integracje.

  4. 4

    Wprowadź nazwę

    W wyświetlonym oknie dialogowym wprowadź opisową nazwę dla swojego klucza API. Pomoże Ci to zidentyfikować klucz później (np. „Integracja Power BI” lub „Synchronizacja CRM”).

  5. 5

    Skopiuj swój klucz

    Po kliknięciu „Utwórz” Twój klucz API zostanie wyświetlony. Kliknij przycisk kopiowania, aby skopiować go do schowka. Klucz zostanie pokazany tylko raz!

Format klucza API

Klucze API mają następujący format:

nm_{company}_{random_32_chars}
  • Wszystkie klucze zaczynają się od „nm_”
  • Prefiks specyficzny dla firmy w celu identyfikacji
  • 32 losowe znaki dla bezpieczeństwa

Używanie Twojego klucza API

Dołącz klucz API w nagłówku X-API-Key przy każdym żądaniu:

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

Uprawnienia klucza API

Każdy klucz ma uprawnienia wybrane podczas jego tworzenia. Punkt końcowy zwraca 403, jeśli klucz nie posiada wymaganego uprawnienia. Serwer MCP zwraca zamiast tego błąd narzędzia.

UprawnienieOpis
DEVICES_READWyświetlanie i odczyt urządzeń, podsumowania floty oraz historii poleceń. Wymagane przez punkty końcowe GET /assets, interfejs BI API oraz narzędzia odczytu urządzeń MCP. GET /device-user-logins wymaga uprawnienia DEVICES_READ, podobnie jak inne operacje odczytu urządzeń.
POLICIES_READWyświetlanie i odczyt zasad. Wymagane przez GET /policies, GET /policies/POLICY_ID oraz narzędzia zasad MCP.
DEVICES_COMMANDWysyłanie polecenia do jednego urządzenia: lock, lost mode, message, status report, location update, policy sync, reboot, shutdown, launch app, clear app data oraz change policy (co wymaga również POLICIES_READ). Opcjonalne (opt-in) i nigdy nie wynikające z innego uprawnienia. Musi być połączone z DEVICES_READ. Wymagane przez standardowe punkty końcowe poleceń POST oraz narzędzia poleceń MCP. Zgłaszanie logowań i wylogowań użytkowników urządzeń (POST /device-user-logins i POST /device-user-logins/logout) wymaga uprawnienia DEVICES_COMMAND, które służy do wysyłania poleceń do urządzeń; klucz może je otrzymać tylko razem z DEVICES_READ. Sesje użytkowników urządzeń nie mają własnego uprawnienia. API sesji użytkowników urządzeń
DEVICES_COMMAND_DESTRUCTIVEWykonywanie poleceń destrukcyjnych na jednym urządzeniu: wyczyszczenie danych, zresetowanie lub zmiana blokady ekranu, zrzeczenie się własności oraz odinstalowanie aplikacji. Są one wykonywane natychmiastowo, bez etapu zatwierdzania w portalu. Funkcja opcjonalna, niezależna od DEVICES_COMMAND, która musi być połączona z DEVICES_READ. Firma musi również włączyć polecenia destrukcyjne w sekcji dostępu agenta AI w portalu. Wymagane przez punkty końcowe poleceń destrukcyjnych oraz narzędzia poleceń destrukcyjnych MCP.
PROVISIONINGTwórz kody QR do aprowizacji dla zasad firmy. Każdy kod QR zawiera nowy token rejestracji, który wygasa po 24 godz. Wymaga zgody (opt-in) i musi być połączony z POLICIES_READ. Tylko użytkownik portalu, który ma uprawnienia do aprowizacji urządzeń i dostęp do wszystkich zasad, może utworzyć klucz z tym uprawnieniem. Wymagane przez POST /policies/POLICY_ID/provisioning-qr-codes oraz narzędzie MCP create_provisioning_qr_code. API kodów QR do aprowizacji
EXPORT_READStarsze uprawnienie (legacy). Żaden punkt końcowy ani narzędzie go nie sprawdza, a nowe klucze nie mogą być już z nim tworzone.
POLICIES_WRITEKlucz API z uprawnieniem POLICIES_WRITE (Zmiany w zasadach), połączony z POLICIES_READ. Tylko użytkownik portalu z uprawnieniami do edycji zasad może utworzyć klucz z uprawnieniem POLICIES_WRITE. Wymagane przez punkty końcowe POST oraz narzędzia do zmiany zasad MCP. API zmian zasad
LIBRARY_MANAGELIBRARY_MANAGE to wrażliwe uprawnienie obejmujące całą firmę, dotyczące przesyłania APK i zarządzania aplikacjami. Nie zapewnia przypisywania zasad, poleceń dla urządzeń, aprowizacji ani operacji na koncie. API przesyłania APK · API aplikacji biblioteki

Gdzie przesyłać klucz

Interfejs REST API akceptuje klucz wyłącznie w nagłówku X-API-Key. Punkt końcowy MCP akceptuje nagłówek X-API-Key lub Authorization: Bearer, po którym następuje klucz.

Przewodnik po serwerze MCP

Limity żądań i nagłówki

Punkty końcowe odczytu REST nie stosują limitu na klucz w aplikacji Nomid, jednak zaleca się zaimplementowanie w kliencie mechanizmu wycofywania się (backoff) w przypadku błędu 429. Punkt końcowy MCP zezwala na 60 żądań na minutę na klucz. Polecenia urządzeń, zmiany zasad (każde wywołanie propose i apply) oraz kody QR do aprowizacji współdzielą limit zapisu wynoszący 10 żądań na minutę na klucz, łącznie dla REST i MCP. Połączenie „Zaloguj się przez Nomid” (Sign in with Nomid) ma takie same limity MCP i zapisu, liczone na połączenie.

Odpowiedź HTTP 429 zawiera nagłówek Retry-After z liczbą sekund do odczekania. Gdy polecenie MCP, zmiana zasad lub wywołanie narzędzia aprowizacji przekroczy limit zapisu, treść błędu narzędzia podaje zamiast tego liczbę sekund. Interfejs API nie ustawia nagłówków X-RateLimit-Limit, X-RateLimit-Remaining ani X-RateLimit-Reset.

Najlepsze praktyki w zakresie bezpieczeństwa

  • Nigdy nie ujawniaj kluczy API w kodzie po stronie klienta ani w publicznych repozytoriach
  • Regularnie rotuj klucze i unieważniaj nieużywane klucze
  • Przechowuj klucze w zmiennych środowiskowych, nie w kodzie
  • Użyj minimalnych uprawnień niezbędnych do twojej integracji

Błędy uwierzytelniania

API zwraca specyficzne kody błędów dotyczące problemów z uwierzytelnianiem:

Kod statusuOpis
401Brakujący lub nieprawidłowy klucz API
403Klucz API nie ma wymaganych uprawnień
429Przekroczono limit żądań

Wybierz swój czas

Ładowanie...
Otwórz kalendarz rezerwacji