OAuth 2.0 to protokół, który pozwala aplikacji poprosić o uprawnienia do odczytu lub modyfikowania danych na koncie monday użytkownika. Po zakończeniu procesu OAuth aplikacja otrzymuje token dostępu przypisany do użytkownika. Token ten zapewnia dostęp do określonych zakresów uprawnień.

Konfiguracja OAuth dla aplikacji obejmuje dwa kroki: konfigurację aplikacji i przejście standardowego przepływu OAuth.

Konfigurowanie zakresów uprawnień i adresów URL przekierowania

Najpierw skonfiguruj zakresy uprawnień i adresy URL przekierowania aplikacji. Jeśli nie masz jeszcze aplikacji, wykonaj te kroki, aby utworzyć aplikację w interfejsie monday i znaleźć jej client_id oraz client_secret.

Po utworzeniu aplikacji skonfiguruj zakresy uprawnień i adresy URL przekierowania na karcie OAuth (OAuth tab) w Centrum deweloperów (Developer Center).

Zakresy uprawnień

Zakresy OAuth określają, jakie działania może wykonywać aplikacja. Każdy punkt końcowy monday API wymaga określonego zakresu uprawnień. Znajdziesz go w dokumentacji API.

Gdy prosisz użytkownika monday o przyznanie aplikacji dostępu, musisz określić, do których z obsługiwanych poniżej zakresów aplikacja ma uzyskać dostęp:

Zakres	Opis
account:read	Odczyt ogólnych informacji o koncie
assets:read	Odczyt danych z zasobów dostępnych dla użytkownika
boards:read	Odczyt danych użytkownika z tablic
boards:write	Modyfikowanie danych użytkownika na tablicach
departments:read	Odczyt danych działów na koncie
departments:write	Modyfikowanie działów na koncie
docs:read	Odczyt dokumentów użytkownika
docs:write	Modyfikowanie dokumentów użytkownika
me:read	Odczyt informacji profilowych użytkownika
notifications:write	Wysyłanie powiadomień w imieniu użytkownika
tags:read	Odczyt tagów na koncie
teams:read	Odczyt informacji o zespołach na koncie
teams:write	Modyfikowanie zespołów na koncie
updates:read	Odczyt aktualizacji i odpowiedzi widocznych dla użytkownika
updates:write	Publikowanie i edytowanie aktualizacji w imieniu użytkownika
users:read	Odczyt informacji profilowych użytkowników konta
users:write	Modyfikowanie informacji profilowych użytkowników konta
webhooks:read	Odczyt konfiguracji istniejących webhooków
webhooks:write	Tworzenie i modyfikowanie webhooków
workspaces:read	Odczyt danych o obszarach roboczych użytkownika
workspaces:write	Modyfikowanie obszarów roboczych użytkownika

Adresy URL przekierowania

Gdy użytkownik monday zaakceptuje lub odrzuci prośbę aplikacji o autoryzację, zostanie przekierowany z powrotem do aplikacji pod określony adres redirect_uri. Możesz użyć kilku adresów URL, aby przekierowywać użytkowników na różne strony w zależności od kontekstu.

Przepływ OAuth

Po utworzeniu i skonfigurowaniu aplikacji monday możesz przejść standardowy przepływ OAuth. Pomyślna autoryzacja OAuth między aplikacją, użytkownikiem i serwerem OAuth monday przebiega w następującej kolejności:

1. Wyślij żądanie autoryzacji i przekieruj użytkownika do adresu URL OAuth monday z identyfikatorem klienta: https://auth.monday.com/oauth2/authorize
2. Użytkownik zobaczy zakresy uprawnień, o które prosi aplikacja, i zaakceptuje żądanie.
3. Po zaakceptowaniu żądania użytkownik zostanie przekierowany pod określony adres URL przekierowania. W parametrach zapytania znajdzie się tymczasowy kod autoryzacyjny.
4. Backend aplikacji wyśle żądanie POST do punktu końcowego żądania tokenu, przekazując ten kod. Punkt końcowy tokenu zwróci token dostępu. Token zapewnia aplikacji dostęp do monday API w imieniu użytkownika i pozostaje ważny do momentu odinstalowania aplikacji przez użytkownika.

Żądanie autoryzacji

Pierwszym krokiem przepływu OAuth jest wysłanie żądania autoryzacji i przekierowanie użytkownika na stronę OAuth monday. Adres URL żądania OAuth to: https://auth.monday.com/oauth2/authorize.

Przykład: GET https:/auth.monday.com/oauth2/authorize?client_id=1111

Parametr	Opis	Wartość domyślna	Wymagany
client_id	Identyfikator aplikacji. Znajdziesz go na karcie Basic Information.		Tak
redirect_uri	Adres URL, pod który użytkownik ma wrócić po zaakceptowaniu lub odrzuceniu prośby. Musi być jednym z adresów URL przekierowania dodanych do aplikacji.	Jeśli skonfigurowano tylko jeden redirect_uri, zostanie użyty ten adres.	Tak, jeśli skonfigurowano więcej niż jeden redirect_uri
scope	Lista zakresów OAuth oddzielonych spacjami. Określa uprawnienia, o które prosi aplikacja. Wszystkie żądane zakresy muszą być zgodne z listą skonfigurowaną w aplikacji.	Pełna lista zakresów skonfigurowana w aplikacji	Nie
state	Dowolna wartość przekazywana do aplikacji po zaakceptowaniu lub odrzuceniu prośby. Użyj unikalnego parametru state, aby zapobiec atakom polegającym na fałszowaniu żądań, i sprawdzaj jego wartość na każdym etapie przepływu OAuth.		Nie
app_version_id	Unikalny identyfikator wersji aplikacji. Umożliwia współpracownikom aplikacji przejście przepływu OAuth dla wskazanej wersji aplikacji - opublikowanej lub roboczej. Znajdziesz go w adresie URL aplikacji, za app_versions. Ta opcja nie działa w przypadku wycofanych wersji ani osób, które nie współpracują przy aplikacji.	Adres URL wywołania zwrotnego opublikowanej wersji, określony w Centrum deweloperów w sekcji callback URL. Jeśli nie ma opublikowanej wersji, zostanie użyta najnowsza wersja utworzona w aplikacji.	Nie
force_install_if_needed	Umożliwia płynne przejście przepływu OAuth: jeśli aplikacja nie jest zainstalowana, użytkownik zostanie automatycznie przekierowany na stronę jej instalacji. Po zainstalowaniu aplikacji przez administratora nastąpi powrót na stronę OAuth w celu dokończenia procesu uwierzytelniania.		Nie

Przekierowanie

Po przyznaniu aplikacji uprawnień w kroku 2 użytkownik zostanie przekierowany do aplikacji w ramach kroku 3. Przekierowanie nastąpi pod podany adres redirect_uri. Do parametrów zapytania dodamy kod autoryzacyjny, zakres i state:

Parametr	Opis
code	Wygenerowany kod autoryzacyjny. Jest ważny przez 10 minut.
state	Parametr state przekazany w poprzednim kroku.

Żądanie tokenu i odpowiedź

Po uzyskaniu kodu autoryzacyjnego z punktu końcowego autoryzacji możesz wymienić go na token dostępu, aby wykonywać żądania do monday API. Kod autoryzacyjny jest ważny tylko przez 10 minut. Po tym czasie musisz wysłać kolejne żądanie, aby uzyskać nowy kod.

Struktura żądania

Żądanie musi używać metody HTTP POST. Adres URL tokenu to https://auth.monday.com/oauth2/token.

Parametr	Opis
client_id	Unikalny identyfikator aplikacji. Znajdziesz go na karcie Basic Information.
client_secret	Tajny klucz aplikacji. Znajdziesz go na karcie Basic Information.
redirect_uri	Ten parametr służy wyłącznie do weryfikacji - nie powoduje przekierowania. Jego wartość musi być taka sama jak wartość podana w kroku żądania autoryzacji.
code	Kod autoryzacyjny z poprzedniego kroku.

Struktura odpowiedzi

W przypadku powodzenia nagłówek odpowiedzi zawiera status 200 OK, a jej treść - następujące dane JSON:

Klucz	Opis
access_token	Token dostępu używany do wykonywania żądań API. Tokeny nie wygasają i pozostają ważne do momentu odinstalowania aplikacji przez użytkownika. Nasz przepływ OAuth nie obsługuje tokenów odświeżania.
token_type	Wszystkie tokeny OAuth monday są tokenami bearer.
scope	Lista zakresów przyznanych dla tego tokenu dostępu, oddzielonych przecinkami.

Treść odpowiedzi w formacie JSON będzie wyglądać tak:

{
   "access_token": "NgeFeX...FEmEka", 
   "token_type": "Bearer",
   "scope": "boards:write boards:read"
}

Przepływ OAuth dla użytkowników z wieloma kontami

Niektórzy użytkownicy monday.com należą do kilku kont. Aplikacja może więc chcieć określić, dla którego konta użytkownik ma zostać autoryzowany. W standardowym przepływie OAuth użytkownik może wybrać konto monday.com, na którym chce przeprowadzić autoryzację, z menu rozwijanego.

Jeśli chcesz mieć pewność, że użytkownik autoryzuje konkretne konto, możesz zmienić adres URL autoryzacji na podstawie adresu URL konta.

Możesz to zrobić na dwa sposoby, używając identyfikatora konta (slug): konstruując adres URL lub dodając parametr zapytania.

Konstruowanie adresu URL

Ta metoda polega na skonstruowaniu adresu URL z identyfikatorem konta (slug) lub subdomeną, czyli pierwszą częścią adresu URL przed .monday.com. Użytkownicy nadal mogą zmienić konto za pomocą menu rozwijanego, ale wskazany przez Ciebie identyfikator będzie wybrany domyślnie. Możesz łatwo uzyskać identyfikator konta, pobierając dane konta za pomocą monday API.

Załóżmy, że pobraliśmy dane konta, a jego identyfikator to awesomeapp. Adres URL przepływu OAuth będzie wyglądać tak:

https://awesomeapp.monday.com/oauth2/authorize?client_id=<CLIENT_ID>&redirect_uri=<YOUR_URL>

Dodawanie parametru zapytania

Zamiast konstruować adres URL, możesz dodać do niego parametr zapytania subdomain=<ACCOUNT_SLUG>, aby utworzyć link z identyfikatorem konta. W przeciwieństwie do poprzedniej metody użytkownicy nie mogą zmienić konta za pomocą menu rozwijanego - muszą użyć wskazanego identyfikatora.

Korzystając z powyższego przykładu, otrzymasz taki adres URL:
https://auth.monday.com/oauth2/authorize?client_id=<CLIENT_ID>&redirect_uri=<YOUR_URL>&subdomain=awesomeapp

Kody błędów

W przypadku dowolnego błędu użytkownik zostanie przekierowany z powrotem pod określony adres redirect_uri. Możliwe kody błędów:

Kod błędu	Opis
400	invalid_request
403	unauthorized_client
403	access_denied
403	invalid_scope
500	server_error
500	temporary_unavailable

📘 Dołącz do naszej społeczności deweloperów!

Stworzyliśmy społeczność dla deweloperów, w której możesz wyszukiwać wcześniejsze dyskusje, aby znaleźć rozwiązania, zadawać pytania, poznawać nowe funkcje i aktualizacje oraz uczyć się wskazówek i trików od innych deweloperów. Dołącz do nas! 😎