OAuth untuk aplikasi mitra
Aplikasi mitra, alat otomatisasi, atau aplikasi kustom yang bekerja untuk pengguna MonoChat dapat memanggil API fungsi kustom (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) dengan token akses OAuth, bukan token API. Pengguna menyetujui aplikasi di halaman MonoChat, memilih organisasi yang boleh dijangkaunya, dan dapat mencabutnya kapan saja di Aplikasi terhubung pada pengaturan profil.
Token API tetap berfungsi di endpoint yang sama. OAuth adalah pilihan untuk aplikasi yang bertindak atas nama orang lain: aplikasi tidak pernah melihat kata sandi atau token API, dan setiap pengguna dapat memutusnya sendiri.
Panggilan dengan token akses berjalan sebagai pengguna yang menyetujui aplikasi, dengan peran pengguna tersebut. Panggilan hanya menjalankan metode kustom organisasi, dan hanya di organisasi tempat pengguna menjadi agen.
Dapatkan klien
Minta klien untuk aplikasi Anda kepada MonoChat. MonoChat mendaftarkannya dengan:
- nama aplikasi, yang ditampilkan halaman persetujuan dan Aplikasi terhubung;
- URI pengalihannya, dicocokkan persis: alamat
https, atauhttpdilocalhost,127.0.0.1, atau[::1](port apa pun); - cakupan yang boleh dimintanya:
custom-functions:rununtuk API ini.
Anda menerima ID klien (diawali monochat_rc_) dan rahasia klien (diawali monochat_cs_). Rahasia hanya ditampilkan sekali; MonoChat hanya menyimpan hash-nya. Simpan di server Anda, jangan di browser atau aplikasi seluler.
Aplikasi yang tidak dapat menyimpan rahasia, misalnya yang berjalan di browser atau di komputer pengguna, dapat menggunakan URL dokumen metadata klien sebagai ID klien, seperti klien MCP. Aplikasi tersebut lalu tidak mengirim rahasia.
Endpoint
Metadata server otorisasi di https://app.monochat.ai/.well-known/oauth-authorization-server mencantumkan semua endpoint. Pada instalasi white-label atau yang di-host sendiri, gunakan alamat instalasi tersebut.
| Pengaturan | Nilai |
|---|---|
| Endpoint otorisasi | https://app.monochat.ai/oauth/authorize |
| Endpoint token | https://app.monochat.ai/oauth/token |
| Endpoint pencabutan | https://app.monochat.ai/oauth/revoke |
| Sumber daya | https://app.monochat.ai/api/custom-functions |
| Cakupan | custom-functions:run |
| Autentikasi klien | HTTP Basic, atau client_id dan client_secret di body permintaan |
Metadata sumber daya itu sendiri ada di https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions.
Hubungkan pengguna
MonoChat menggunakan alur kode otorisasi dengan PKCE (S256). Pengguna perlu sudah menyiapkan verifikasi dua langkah (lewat email atau aplikasi autentikator).
- Arahkan pengguna ke endpoint otorisasi dengan
response_type=code,client_idAnda,redirect_uriyang terdaftar,scope=custom-functions:run,resource=https://app.monochat.ai/api/custom-functions, sebuahstate, dancode_challengedengancode_challenge_method=S256. - Pengguna masuk ke MonoChat bila perlu. Halaman persetujuan menyebut nama aplikasi Anda dan menampilkan Menjalankan metode kustom atas nama Anda. Pengguna dapat memilih Organisasi yang boleh dijangkau aplikasi (semua miliknya bila tidak memilih), memasukkan kode konfirmasi 6 digit, lalu mengklik Izinkan.
- MonoChat mengembalikan pengguna ke
redirect_uriAnda dengancode,state, daniss. Jika pengguna mengklik Tolak, yang dikirim adalaherror=access_denied. - Tukarkan kode di endpoint token dalam 5 menit:
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>
Jawabannya berisi access_token (diawali monochat_at_) yang berlaku selama expires_in detik (satu jam), refresh_token (diawali monochat_rt_), dan scope yang diberikan.
Panggil API
Kirim token akses sebagai 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 | Kapan |
|---|---|
401 | Token tidak dikenal, kedaluwarsa, atau dicabut, atau diterbitkan untuk sumber daya lain, seperti server MCP. Header WWW-Authenticate menunjuk ke metadata sumber daya. |
403 | Organisasi bukan salah satu yang diizinkan pengguna untuk aplikasi, pengguna tidak punya akses ke organisasi, atau izin tidak mencakup custom-functions:run. |
429 | Batas tercapai; tunggu selama detik di Retry-After. Panggilan dihitung per menit: 120 per izin dan 1.200 per klien, selain batas organisasi sendiri untuk endpoint ini. |
Perbarui dan cabut
- Perbarui: sebelum token akses kedaluwarsa, panggil endpoint token dengan
grant_type=refresh_tokendanrefresh_token. Setiap pembaruan mengembalikan refresh token baru; gunakan yang baru. Refresh token yang dipakai lagi lebih dari satu menit setelah diganti mengakhiri izin. - Kedaluwarsa: izin berakhir 90 hari setelah pembaruan terakhir, saat pengguna mencabutnya di Aplikasi terhubung, atau saat pengguna mengubah atau mengatur ulang kata sandinya. Pengguna lalu harus menyetujui aplikasi lagi.
- Cabut: untuk memutus pengguna, kirim token akses atau refresh token ke endpoint pencabutan dengan autentikasi klien Anda:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>
Menghubungkan pengguna yang sama ke aplikasi Anda lagi menggantikan izin sebelumnya.