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
Zaloguj się do Portalu Nomid
Otwórz przeglądarkę i przejdź do Portalu Nomid. Zaloguj się przy użyciu swoich danych administratora.
- 2
Przejdź do Integracji
Po zalogowaniu przejdź do sekcji Ustawienia Firmy i wybierz zakładkę Integracje.
- 3
Kliknij Utwórz klucz API
Kliknij przycisk "Utwórz klucz API" znajdujący się w prawym górnym rogu strony Integracje.
- 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
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.
| Uprawnienie | Opis |
|---|---|
| DEVICES_READ | Wyś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_READ | Wyświetlanie i odczyt zasad. Wymagane przez GET /policies, GET /policies/POLICY_ID oraz narzędzia zasad MCP. |
| DEVICES_COMMAND | Wysył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_DESTRUCTIVE | Wykonywanie 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. |
| PROVISIONING | Twó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_READ | Starsze uprawnienie (legacy). Żaden punkt końcowy ani narzędzie go nie sprawdza, a nowe klucze nie mogą być już z nim tworzone. |
| POLICIES_WRITE | Klucz 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_MANAGE | LIBRARY_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.
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 statusu | Opis |
|---|---|
| 401 | Brakujący lub nieprawidłowy klucz API |
| 403 | Klucz API nie ma wymaganych uprawnień |
| 429 | Przekroczono limit żądań |