Połącz swoją aplikację z Notiondesk za pomocą protokołu OAuth

Notiondesk OAuth pozwala innym klientom Notiondesk połączyć Twoją aplikację ze swoim obszarem roboczym bez udostępniania klucza API. Klient loguje się do Notiondesk, sprawdza, o co prosi Twoja aplikacja i zatwierdza żądanie. Twoja aplikacja otrzymuje token dostępu do interfejsu REST API Notiondesk, który klient może w dowolnym momencie cofnąć. W tym artykule opisano rejestrację aplikacji, uruchomienie przepływu kodu autoryzacji OAuth 2.0 z PKCE, odświeżanie tokenów i obsługę błędów.

Kiedy używać protokołu OAuth zamiast klucza API

Każda trasa API Notiondesk akceptuje oba poświadczenia i odpowiada na nie w ten sam sposób: z tymi samymi zakresami, odpowiedziami i błędami.

Co Twoja aplikacja musi wiedzieć

Odczytaj punkty końcowe z dokumentu metadanych serwera autoryzacji, zamiast kodować je na stałe.

Uruchom klienta OAuth na serwerze. Klienci przeglądarkowi nie są obsługiwani: zachowaj wymianę tokenów, tokeny i każde wywołanie API w swoim zapleczu.

Krok 1: Zarejestruj swoją aplikację

Zarejestruj się raz za pomocą dynamicznej rejestracji klienta :

Odpowiedź 201 Created zawiera Twoje client_id oraz, ponieważ poprosiłeś o client_secret_post, client_secret. Sekret jest wyświetlany raz: przechowuj go razem z innymi sekretami serwera.

Dzięki "token_endpoint_auth_method": "none" Twoja aplikacja jest publicznym klientem bez żadnych tajemnic, a PKCE chroni wymianę kodu.

Zamiast rejestrować się, możesz użyć adresu URL HTTPS dokumentu metadanych klienta jako client_id. Notiondesk pobiera dokument, gdy klient autoryzuje Twoją aplikację i zapisuje go w pamięci podręcznej na okres do pięciu minut.

Reguły przekierowania URI

curl -X POST "https://api.notiondesk.so/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Acme Reports", "redirect_uris": ["https://acme.example/oauth/callback"], "token_endpoint_auth_method": "client_secret_post"}'

• Użyj https lub http na hoście pętli zwrotnej: 127.0.0.1, localhost lub [::1].

• Przekierowanie pętli zwrotnej pasuje do dowolnego portu. Każde inne przekierowanie musi pasować dokładnie.

• Symbole wieloznaczne, fragmenty, dane uwierzytelniające przed hostem (user@), ukośniki odwrotne, znaki spoza zestawu ASCII oraz hosty zakodowane procentowo są odrzucane.

• Host, którego klient widzi na ekranie zgody, pochodzi z Twoich adresów URI przekierowania lub z Twojego adresu URL client_id. Rejestruj tylko hosty, których jesteś właścicielem.

Krok 2: Przekieruj klienta do Notiondesk

Utwórz losowy code_verifier, a następnie wyprowadź code_challenge jako skrót SHA-256 weryfikatora, zakodowany w base64url ( PKCE ). Przekieruj przeglądarkę klienta do:

https://api.notiondesk.so/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Facme.example%2Foauth%2Fcallback
  &scope=read%20write
  &state=RANDOM_STATE
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.notiondesk.so

• resource jest wymagane i musi wynosić dokładnie https://api.notiondesk.so: małe litery, bez ukośnika na końcu, bez ścieżki. Brakująca lub inna wartość odpowiada invalid_request.

• scope to lista rozdzielona spacjami. Pytaj tylko o zakresy używane przez Twoją aplikację.

• state chroni przed fałszowaniem żądań między witrynami. Sprawdź to, gdy klient wróci.

Token wydany dla interfejsu API REST Notiondesk działa tylko z interfejsem API REST. Token wydany dla Workspace MCP jest odrzucany przez interfejs API REST i odwrotnie.

Krok 3: Klient zatwierdza Twoją aplikację

Notiondesk wyświetla ekran zgody. Klient loguje się i widzi nazwę i hosta Twojej aplikacji, swoją przestrzeń roboczą oraz zakresy z Twojego żądania, na które zezwala jego rola. Zatwierdza lub odrzuca całe żądanie.

Zakresy, jakie może otrzymać Twoja aplikacja, zależą od roli klienta w obszarze roboczym:

admin pozwala Twojej aplikacji zmienić branding Centrum pomocy, skonfigurować integracje, których skrypty ładują się w publicznym Centrum pomocy, oraz usunąć przekierowania. Poproś o to tylko wtedy, gdy Twoja aplikacja korzysta z tych tras.

Klient nie może zaakceptować wniosku, gdy:

• ich rola nie pozwala na żaden z zakresów, o które prosiłeś;

• Ich przestrzeń robocza nie ma dostępu do API. Na ekranie zgody pojawia się komunikat: „Plan przestrzeni roboczej nie obejmuje dostępu do API”. Dostęp do API wymaga planu Enterprise.

Po zatwierdzeniu przeglądarka powraca do redirect_uri z code, state i iss, czyli identyfikatorem serwera autoryzacji Notiondesk. Jeśli klient odmówi, przekierowanie przenosi error=access_denied.

Krok 4: Wymiana kodu na tokeny

Kod jest ważny przez 60 sekund i działa jednorazowo:

Pomiń client_secret dla klienta publicznego. Odpowiedź:

scope wyświetla zakresy przyznane przez klienta, które mogą być mniejsze niż te, o które prosiłeś. Przechowuj oba tokeny na swoim serwerze.

Krok 5: Wywołanie interfejsu API Notiondesk

Wyślij token dostępu jako token nośnika, dokładnie tak jak klucz API:

Zakresy tokena są ograniczone do bieżącej roli zatwierdzającego klienta: klient, którego rola została zmieniona na Widz, opuszcza aplikację tylko z read, a trasa wymagająca brakującego zakresu odpowiada 403 insufficient_scope.

Budżety limitów stawek i wartości Idempotency-Key należą do grantu. Każde zatwierdzenie to nowy grant z własnymi budżetami i kluczami, a odświeżenie tokena zachowuje oba te elementy.

Krok 6: Odśwież token dostępu

Token dostępu jest ważny przez godzinę. Przed jego wygaśnięciem wymień token odświeżania na nową parę:

Każde odświeżenie zwraca nowy token odświeżania ważny przez 30 dni i unieważnia ten, który wysłałeś. Zachowaj nowy token odświeżania przed użyciem nowego tokena dostępu.

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=THE_CODE \
  -d code_verifier=YOUR_CODE_VERIFIER \
  -d redirect_uri=https://acme.example/oauth/callback

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8f3c...",
  "scope": "read write"
}

curl "https://api.notiondesk.so/sites" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "nd-version: 2026-10-16"

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=refresh_token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d refresh_token=THE_REFRESH_TOKEN

Nigdy nie używaj ponownie tokena odświeżania. Wysłanie już użytego tokena unieważnia całe przyznanie, w tym token dostępu, ponieważ ponowne użycie oznacza, że ​​token został skopiowany. Klient musi wtedy ponownie autoryzować aplikację.

Jak klienci mogą cofnąć Twoją aplikację

Właściciele i administratorzy przestrzeni roboczej widzą wszystkie aplikacje z dostępem do ich przestrzeni roboczej w Ustawieniach > Deweloperzy > Połączone aplikacje . Aplikacje korzystające z interfejsu API REST wyświetlają interfejs API REST w kolumnie Dostęp , wraz z nazwą aplikacji, osobą, która ją autoryzowała, jej zakresami i ostatnią aktywnością. Polecenie „Revoke” natychmiast kończy przyznanie uprawnień: token dostępu i token odświeżania przestają działać przy następnym żądaniu.

Dotacja również kończy się sama:

• po 30 dniach bez odświeżania;

• gdy jego token odświeżania jest ponownie wykorzystywany.

Jeśli klient zatwierdzający nie posiada roli wymaganej przez trasę lub plan obszaru roboczego nie ma dostępu do API, żądania są odrzucane. Są one ponownie obsługiwane, jeśli rola lub plan powrócą przed zakończeniem przyznania.

Rozwiązywanie problemów Notiondesk OAuth

Punkty końcowe autoryzacji i tokena odpowiadają na standardowe błędy OAuth, a nie na błędy API Notiondesk:

{"error": "invalid_grant", "error_description": "Invalid authorization code."}

Punkt końcowy autoryzacji sam wyświetla te błędy i nigdy nie przekierowuje nieprawidłowego żądania do redirect_uri. Odmowa zgody dociera do Twojej aplikacji dopiero jako przekierowanie error=access_denied.

Wywołania samego API odpowiadają na błąd API Notiondesk . Wygasły lub unieważniony token dostępu odpowiada kodem 401 authentication_error, wyświetlając komunikat „Nieprawidłowy lub brakujący klucz API”, taki sam jak w przypadku bezużytecznego klucza API.

Często zadawane pytania

Co dalej?

• Rozpocznij korzystanie z interfejsu API REST Notiondesk

• Uwierzytelnij się za pomocą interfejsu API Notiondesk, używając kluczy API

• Odłącz lub cofnij dostęp do Workspace MCP