Nowy przepływ OAuth 2.1 wprowadza kilka ważnych zmian w sposobie obsługi tokenów uwierzytelniających przez aplikację. Ten przewodnik opisuje tylko zmiany, które musisz wprowadzić w istniejącej integracji. Żądanie autoryzacji (krok 1 przepływu OAuth) pozostaje bez zmian.

Najważniejsze różnice w nowym przepływie:

• Tokeny dostępu mają teraz termin ważności - musisz obsługiwać ich wygasanie i odświeżanie.
• Tokeny odświeżania - używaj ich, aby uzyskiwać nowe tokeny dostępu bez ponownej autoryzacji użytkownika.
• Unieważnianie tokenów - unieważniaj tokeny, gdy nie są już potrzebne.
• Nowy adres URL punktu końcowego tokenów - wymiana tokenów odbywa się teraz przez inny punkt końcowy.

📘 Dopiero zaczynasz pracę z OAuth?

Jeśli nie masz jeszcze zaimplementowanego OAuth, najpierw zapoznaj się z przewodnikiem OAuth i uprawnienia, a potem wróć tutaj, aby skorzystać z nowego przepływu.

1. Włącz nowy przepływ OAuth

Zanim rozpoczniesz migrację, włącz nowy przepływ OAuth dla wersji aplikacji w Centrum deweloperskim (Developer Center):

1. Otwórz aplikację w Centrum deweloperskim.
2. Przejdź do karty OAuth i uprawnienia (OAuth & Permissions).
3. Utwórz nową wersję roboczą aplikacji. Przełącznik dotyczy konkretnej wersji.
4. Włącz przełącznik Nowy przepływ OAuth (New OAuth Flow) dla wersji roboczej.
5. Przetestuj przepływ, ustawiając wersję roboczą jako Aktywna tylko dla mnie (Active for me).
6. Gdy sprawdzisz, że przepływ działa, opublikuj wersję roboczą.

2. Zaktualizuj adres URL punktu końcowego tokenów

Punkt końcowy autoryzacji pozostaje bez zmian:

GET https://auth.monday.com/oauth2/authorize

Obsługuje teraz PKCE, które dodaje następujące parametry zapytania:

Parametr	Opis	Wymagany
code_challenge	Wartość wyzwania PKCE (zakodowany w base64url skrót SHA-256 z code_verifier). Musi mieć od 43 do 128 znaków. Zobacz sekcję PKCE (Proof Key for Code Exchange) poniżej.	Tak
code_challenge_method	Metoda używana do wygenerowania wartości wyzwania. Obsługiwana jest tylko metoda S256.	Tak

Punkt końcowy wymiany tokenów uległ zmianie:

	Stary przepływ	Nowy przepływ
Adres URL tokenów	POST https://auth.monday.com/oauth2/token	POST https://auth.monday.com/oauth_ms/oauth/token

Zaktualizuj kod backendu, aby używał nowego adresu URL przy wymianie kodów autoryzacyjnych na tokeny.

Żądanie wymiany tokenów obsługuje dodatkowy parametr potrzebny do obsługi PKCE:

Parametr	Opis	Wymagany
code_verifier	Oryginalny ciąg weryfikujący PKCE (od 43 do 128 znaków). Wymagany, jeśli podczas autoryzacji wysłano code_challenge. Zobacz sekcję PKCE (Proof Key for Code Exchange) poniżej.	Tak

Zaktualizowane żądanie wymiany tokenów

curl -X POST https://auth.monday.com/oauth_ms/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "https://yourapp.com/callback"
  }'

📘 Adres URI przekierowania

Parametr redirect_uri jest wymagany w żądaniu wymiany tokenów, jeśli podano go w żądaniu autoryzacji.

Zaktualizowana odpowiedź na żądanie wymiany tokenów

Odpowiedź zawiera teraz refresh_token, a token dostępu ma termin ważności:

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "scope": "boards:read users:read"
}

Klucz	Zmiana względem starego przepływu
access_token	Ma teraz termin ważności. Odczytaj pole exp ze zdekodowanego tokenu JWT, aby sprawdzić znacznik czasu wygaśnięcia. Wcześniej tokeny były ważne do odinstalowania aplikacji przez użytkownika.
refresh_token	Nowy. Użyj go, aby uzyskać nowy token dostępu po wygaśnięciu obecnego.
token_type	Bez zmian. Zawsze Bearer.
scope	Lista przyznanych zakresów oddzielonych spacjami.

3. Zaimplementuj odświeżanie tokenów

Tokeny dostępu mają teraz termin ważności, więc aplikacja musi je odświeżać za pomocą tokenu odświeżania. Nie wymaga to interakcji z użytkownikiem.

POST https://auth.monday.com/oauth_ms/oauth/token

curl -X POST https://auth.monday.com/oauth_ms/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

Odpowiedź zawiera nowy token dostępu i nowy token odświeżania:

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "scope": "boards:read users:read"
}

🚧 Zapisuj najnowszy token odświeżania

Każde odświeżenie zwraca nowy refresh_token. Zawsze zapisuj najnowszy token odświeżania i usuń poprzedni.

Zalecana strategia odświeżania

• Zdekoduj token JWT access_token i odczytaj deklarację exp, aby sprawdzić, kiedy token wygaśnie.
• Odśwież token z wyprzedzeniem, zanim wygaśnie - na przykład gdy do wygaśnięcia pozostanie mniej niż 5 minut.
• Jeśli wywołanie API zwróci 401 Unauthorized, spróbuj odświeżyć token i ponów żądanie.

4. Unieważnij tokeny

Możesz teraz jawnie unieważniać tokeny, gdy nie są już potrzebne - na przykład gdy użytkownik odłączy aplikację.

POST https://auth.monday.com/oauth_ms/oauth/revoke

curl -X POST https://auth.monday.com/oauth_ms/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "token": "TOKEN_TO_REVOKE",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "token_type_hint": "access_token"
  }'

Parametr	Opis	Wymagany
token	Token dostępu lub token odświeżania do unieważnienia. Zależy od wartości token_type_hint.	Tak
client_id	Unikalny identyfikator aplikacji.	Tak
client_secret	Klucz tajny aplikacji.	Tak
token_type_hint	access_token lub refresh_token. Pomaga serwerowi rozpoznać typ tokenu.	Nie

Po pomyślnym wykonaniu żądania odpowiedź zawiera:

{
  "success": true
}

5. Odkrywanie serwera (punkt końcowy well-known)

Usługa OAuth udostępnia punkt końcowy odkrywania zgodny z RFC 8414. Pozwala on klientom automatycznie wykrywać wszystkie punkty końcowe OAuth, obsługiwane zakresy i możliwości bez wpisywania adresów URL na stałe.

GET https://auth.monday.com/oauth_ms/.well-known/oauth-authorization-server

Przykładowa odpowiedź (skrócona):

{
  "issuer": "https://auth.monday.com",
  "authorization_endpoint": "https://auth.monday.com/oauth2/authorize",
  "token_endpoint": "https://auth.monday.com/oauth_ms/oauth/token",
  "registration_endpoint": "https://auth.monday.com/oauth_ms/oauth/register",
  "revocation_endpoint": "https://auth.monday.com/oauth_ms/oauth/revoke",
  "scopes_supported": ["me:read", "boards:read", "boards:write", "..."],
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_post"]
}

Pole	Opis
issuer	Podstawowy adres URL monday.com.
authorization_endpoint	Adres URL, na który przekierowuje się użytkowników w celu autoryzacji.
token_endpoint	Adres URL służący do wymiany kodów na tokeny lub tokeny odświeżania.
registration_endpoint	Adres URL rejestracji dynamicznego klienta (DCR).
revocation_endpoint	Adres URL służący do unieważniania tokenów.
scopes_supported	Pełna lista dostępnych zakresów OAuth.
response_types_supported	Obsługiwane typy odpowiedzi (tylko code).
grant_types_supported	Obsługiwane typy przyznawania uprawnień.
code_challenge_methods_supported	Obsługiwane metody PKCE (tylko S256).
token_endpoint_auth_methods_supported	Sposoby uwierzytelniania klientów w punkcie końcowym tokenów.

📘 Automatycznie skonfiguruj klienta OAuth

Użyj tego punktu końcowego, aby automatycznie skonfigurować klienta OAuth. Nie wymaga uwierzytelniania i jest publicznie dostępny. Pełną odpowiedź znajdziesz pod adresem https://auth.monday.com/oauth_ms/.well-known/oauth-authorization-server.

PKCE (Proof Key for Code Exchange)

PKCE chroni przepływ kodu autoryzacyjnego przed atakami polegającymi na przechwyceniu, szczególnie w przypadku klientów publicznych, takich jak aplikacje mobilne, aplikacje jednostronicowe i narzędzia CLI. Jest wymagane we wszystkich aplikacjach korzystających z nowego przepływu OAuth.

1. Wygeneruj kod weryfikujący

Utwórz kryptograficznie losowy ciąg o długości od 43 do 128 znaków, używając znaków niezastrzeżonych ([A-Z] / [a-z] / [0-9] / - / . / _ / ~).

const crypto = require("crypto");
const codeVerifier = crypto.randomBytes(32).toString("base64url");

2. Oblicz kod wyzwania

Oblicz skrót weryfikatora za pomocą SHA-256 i zakoduj wynik w formacie base64url:

const codeChallenge = crypto
  .createHash("sha256")
  .update(codeVerifier)
  .digest("base64url");

3. Dodaj kod wyzwania do żądania autoryzacji

GET https://auth.monday.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

4. Dodaj weryfikator do żądania wymiany tokenów

curl -X POST https://auth.monday.com/oauth_ms/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "code_verifier": "YOUR_CODE_VERIFIER"
  }'

Serwer sprawdza, czy SHA256(code_verifier) jest zgodne z wartością code_challenge wysłaną podczas autoryzacji. Jeśli wartości się nie zgadzają, żądanie wymiany tokenów zostaje odrzucone.

🚧 Obsługiwana jest tylko metoda S256

Jako metodę wyzwania obsługujemy tylko S256. Zwykłe kody wyzwania nie są akceptowane.

Co pozostaje bez zmian

Poniższe elementy przepływu OAuth pozostają bez zmian i nie wymagają modyfikacji:

• Adres URL autoryzacji: GET https://auth.monday.com/oauth2/authorize (ten sam adres URL i te same parametry).
• Zakresy uprawnień: Te same definicje zakresów i konfiguracja w Centrum deweloperskim.
• Adresy URL przekierowań: Ta sama konfiguracja i te same zasady walidacji.
• Wywołanie zwrotne przekierowania: Te same parametry - code, state i status. Sprawdź status, aby potwierdzić, że użytkownik zatwierdził autoryzację.
• Kod autoryzacyjny: Nadal jest ważny przez 10 minut i wymienia się go w ten sam sposób (zmienia się tylko adres URL punktu końcowego).
• Dane logowania klienta: Te same wartości client_id i client_secret z Centrum deweloperskiego.

6. Migruj starsze tokeny API

Jeśli masz istniejące integracje korzystające ze starszych tokenów aplikacji monday, możesz wymienić je na parę tokenów dostępu i odświeżania OAuth 2.1 za pomocą punktu końcowego migracji - bez ponownego przeprowadzania użytkownika przez proces wyrażania zgody OAuth.

POST https://auth.monday.com/oauth_ms/oauth/migrate

Ten punkt końcowy ma limit liczby żądań. Nie wywołuj go wielokrotnie ani dla dużej liczby tokenów naraz. Jest przeznaczony do jednorazowej migracji każdego tokenu. Jeśli otrzymasz kod statusu 429, przed ponowieniem żądania odczekaj 5 minut. W skrypcie migracyjnym zastosuj wykładnicze opóźnienie między kolejnymi próbami - nie ponawiaj żądania od razu.

Żądanie

curl -X POST https://auth.monday.com/oauth_ms/oauth/migrate \
  -H "Content-Type: application/json" \
  -d '{
    "api_token": "YOUR_LEGACY_API_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

Parametr	Opis	Wymagany
api_token	Starszy token API monday do wymiany.	Tak
client_id	Identyfikator klienta OAuth aplikacji (z ustawień OAuth aplikacji).	Tak
client_secret	Klucz tajny klienta OAuth aplikacji (z ustawień OAuth aplikacji).	Tak

Odpowiedź

Po pomyślnym wykonaniu żądania odpowiedź zawiera nowy token dostępu OAuth 2.1 i token odświeżania:

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "already_migrated": false,
  "migrated_from": {
    "api_token_id": 12345678
  }
}

Pole	Opis
access_token	Nowy token dostępu OAuth 2.1. Używaj go we wszystkich kolejnych wywołaniach API.
refresh_token	Użyj go, aby uzyskać nowy token dostępu po wygaśnięciu obecnego. Zobacz sekcję Zaimplementuj odświeżanie tokenów.
token_type	Zawsze Bearer.
expires_in	Czas ważności tokenu dostępu w sekundach.
migrated_from	Zawiera api_token_id oryginalnego wymienionego tokenu.
already_migrated	Wartość true oznacza, że token został już zmigrowany w poprzednim wywołaniu. Nie utworzono nowego tokenu - zwrócono istniejący.

Po migracji zapisz access_token i refresh_token. Następnie korzystaj ze standardowego przepływu odświeżania tokenów.

Odpowiedzi o błędach

Status	Kod błędu	Opis
400	invalid_request	Brakuje api_token, client_id lub client_secret albo wartość nie jest ciągiem znaków.
400	already_oauth_token	Podany token jest już tokenem OAuth - migracja nie jest potrzebna.
400	personal_tokens_not_supported	Nie można migrować osobistych tokenów API; obsługiwane są tylko tokeny aplikacji.
400	invalid_region	Nie rozpoznano regionu tokenu.
400	api_app_id_mismatch	Wartości client_id i client_secret nie należą do tej samej aplikacji co token.
401	invalid_token	Podpis tokenu jest nieprawidłowy, token wygasł, został unieważniony lub nie został znaleziony.
401	invalid_client	Wartość client_id nie pasuje do client_secret.
403	invalid_request	Migracja tokenów jest obecnie wyłączona.
429	too_many_requests	Przekroczono limit żądań. Przed ponowieniem odczekaj 5 minut.
500	-	Nieoczekiwany błąd serwera.

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

Stworzyliśmy społeczność dla deweloperów, w której możesz przeszukiwać wcześniejsze wątki w poszukiwaniu rozwiązań, zadawać pytania, poznawać nowe funkcje i aktualizacje oraz korzystać ze wskazówek i porad innych deweloperów. Dołącz do nas! 😎