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ć.
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
httpslubhttpnalocalhost,127.0.0.1albo[::1](dowolny port); - zakresami, o które może prosić:
custom-functions:rundla 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.
| Ustawienie | Wartość |
|---|---|
| Endpoint autoryzacji | https://app.monochat.ai/oauth/authorize |
| Endpoint tokenu | https://app.monochat.ai/oauth/token |
| Endpoint unieważniania | https://app.monochat.ai/oauth/revoke |
| Zasób | https://app.monochat.ai/api/custom-functions |
| Zakres | custom-functions:run |
| Uwierzytelnianie klienta | HTTP 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ą).
- Wyślij użytkownika do endpointu autoryzacji z
response_type=code, swoimclient_id, zarejestrowanymredirect_uri,scope=custom-functions:run,resource=https://app.monochat.ai/api/custom-functions, parametremstateicode_challengezcode_challenge_method=S256. - 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.
- MonoChat odsyła użytkownika na Twój
redirect_urizcode,stateiiss. Jeśli użytkownik kliknie Odmów, zamiast tego wysyłaerror=access_denied. - 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 '{}'
| Status | Kiedy |
|---|---|
401 | Token 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. |
403 | Organizacja 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. |
429 | Osią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_tokenirefresh_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ę.