Przejdź do głównej zawartości

OAuth dla aplikacji partnerów

Aplikacja partnera, narzędzie automatyzacji lub własna aplikacja działająca dla użytkownika MonoChat może wywoływać API funkcji niestandardowych (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) z tokenem dostępu OAuth zamiast tokenu API. Użytkownik zatwierdza aplikację na stronie MonoChat, wybiera organizacje, do których może ona sięgać, i w każdej chwili może ją odwołać w Połączone aplikacje w ustawieniach profilu.

Tokeny API nadal działają na tym samym endpoincie. OAuth to opcja dla aplikacji działającej w imieniu innych osób: nigdy nie widzi hasła ani tokenu API, a każdy użytkownik może ją sam odłączyć.

Aplikacja działa jako użytkownik

Wywołanie z tokenem dostępu działa jako użytkownik, który zatwierdził aplikację, z jego rolami. Uruchamia tylko metody niestandardowe organizacji i tylko w organizacjach, w których użytkownik jest agentem.

Uzyskanie klienta​

Poproś MonoChat o klienta dla swojej aplikacji. MonoChat rejestruje go z:

  • nazwą aplikacji, którą pokazują strona zatwierdzenia i Połączone aplikacje;
  • jej adresami URI przekierowania, dopasowywanymi dokładnie: adresy https lub http na localhost, 127.0.0.1 albo [::1] (dowolny port);
  • zakresami, o które może prosić: custom-functions:run dla tego API.

Otrzymujesz ID klienta (zaczyna się od monochat_rc_) i sekret klienta (zaczyna się od monochat_cs_). Sekret jest pokazywany tylko raz; MonoChat przechowuje wyłącznie jego skrót. Trzymaj go na swoim serwerze, nigdy w przeglądarce ani aplikacji mobilnej.

Aplikacja, która nie może przechowywać sekretu, na przykład działająca w przeglądarce lub na komputerze użytkownika, może zamiast tego użyć jako ID klienta adresu URL dokumentu metadanych klienta, tak jak klienci MCP. Wtedy nie wysyła sekretu.

Endpointy​

Metadane serwera autoryzacji pod adresem https://app.monochat.ai/.well-known/oauth-authorization-server wymieniają wszystkie endpointy. W instalacji white label lub hostowanej samodzielnie użyj własnego adresu tej instalacji.

UstawienieWartość
Endpoint autoryzacjihttps://app.monochat.ai/oauth/authorize
Endpoint tokenuhttps://app.monochat.ai/oauth/token
Endpoint unieważnianiahttps://app.monochat.ai/oauth/revoke
Zasóbhttps://app.monochat.ai/api/custom-functions
Zakrescustom-functions:run
Uwierzytelnianie klientaHTTP Basic albo client_id i client_secret w treści żądania

Metadane samego zasobu znajdują się pod adresem https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions.

Połączenie użytkownika​

MonoChat używa przepływu kodu autoryzacji z PKCE (S256). Użytkownik musi mieć skonfigurowaną weryfikację dwuetapową (e-mailem lub aplikacją uwierzytelniającą).

  1. Wyślij użytkownika do endpointu autoryzacji z response_type=code, swoim client_id, zarejestrowanym redirect_uri, scope=custom-functions:run, resource=https://app.monochat.ai/api/custom-functions, parametrem state i code_challenge z code_challenge_method=S256.
  2. Użytkownik w razie potrzeby loguje się do MonoChat. Strona zatwierdzenia podaje nazwę aplikacji i pokazuje Uruchamianie metod niestandardowych w Twoim imieniu. Użytkownik może wybrać Organizacje, do których aplikacja może sięgać (wszystkie jego, gdy nie wybierze żadnej), wpisuje 6-cyfrowy kod potwierdzenia i klika Zezwól.
  3. MonoChat odsyła użytkownika na Twój redirect_uri z code, state i iss. Jeśli użytkownik kliknie Odmów, zamiast tego wysyła error=access_denied.
  4. Wymień kod na endpoincie tokenu w ciągu 5 minut:
curl -X POST https://app.monochat.ai/oauth/token \
-u "<client_id>:<client_secret>" \
-d grant_type=authorization_code \
-d code=<code> \
-d redirect_uri=<redirect_uri> \
-d code_verifier=<code_verifier>

Odpowiedź zawiera access_token (zaczyna się od monochat_at_) ważny przez expires_in sekund (godzinę), refresh_token (zaczyna się od monochat_rt_) i przyznany scope.

Wywołanie API​

Wyślij token dostępu jako token bearer:

curl -X POST https://app.monochat.ai/api/<slug>/custom-functions/<path> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
StatusKiedy
401Token jest nieznany, wygasł lub został unieważniony albo wydano go dla innego zasobu, na przykład serwera MCP. Nagłówek WWW-Authenticate wskazuje metadane zasobu.
403Organizacja nie należy do tych, na które użytkownik zezwolił aplikacji, użytkownik nie ma dostępu do organizacji albo zgoda nie obejmuje custom-functions:run.
429Osiągnięto limit; odczekaj liczbę sekund z Retry-After. Wywołania są liczone na minutę: 120 na zgodę i 1200 na klienta, oprócz własnego limitu organizacji dla tego endpointu.

Odświeżanie i unieważnianie​

  • Odświeżanie: zanim token dostępu wygaśnie, wywołaj endpoint tokenu z grant_type=refresh_token i refresh_token. Każde odświeżenie zwraca nowy token odświeżania; używaj nowego. Token odświeżania użyty ponownie ponad minutę po zastąpieniu kończy zgodę.
  • Wygaśnięcie: zgoda kończy się 90 dni po ostatnim odświeżeniu, gdy użytkownik odwoła ją w Połączone aplikacje albo gdy zmieni lub zresetuje hasło. Użytkownik musi wtedy ponownie zatwierdzić aplikację.
  • Unieważnianie: aby odłączyć użytkownika, wyślij token dostępu lub odświeżania na endpoint unieważniania z uwierzytelnieniem klienta:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

Ponowne połączenie tego samego użytkownika z Twoją aplikacją zastępuje jego wcześniejszą zgodę.