Lewati ke konten utama

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.

Aplikasi bertindak sebagai pengguna

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, atau http di localhost, 127.0.0.1, atau [::1] (port apa pun);
  • cakupan yang boleh dimintanya: custom-functions:run untuk 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.

PengaturanNilai
Endpoint otorisasihttps://app.monochat.ai/oauth/authorize
Endpoint tokenhttps://app.monochat.ai/oauth/token
Endpoint pencabutanhttps://app.monochat.ai/oauth/revoke
Sumber dayahttps://app.monochat.ai/api/custom-functions
Cakupancustom-functions:run
Autentikasi klienHTTP 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).

  1. Arahkan pengguna ke endpoint otorisasi dengan response_type=code, client_id Anda, redirect_uri yang terdaftar, scope=custom-functions:run, resource=https://app.monochat.ai/api/custom-functions, sebuah state, dan code_challenge dengan code_challenge_method=S256.
  2. 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.
  3. MonoChat mengembalikan pengguna ke redirect_uri Anda dengan code, state, dan iss. Jika pengguna mengklik Tolak, yang dikirim adalah error=access_denied.
  4. 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 '{}'
StatusKapan
401Token tidak dikenal, kedaluwarsa, atau dicabut, atau diterbitkan untuk sumber daya lain, seperti server MCP. Header WWW-Authenticate menunjuk ke metadata sumber daya.
403Organisasi bukan salah satu yang diizinkan pengguna untuk aplikasi, pengguna tidak punya akses ke organisasi, atau izin tidak mencakup custom-functions:run.
429Batas 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_token dan refresh_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.