Μετάβαση στο κύριο περιεχόμενο

OAuth για εφαρμογές συνεργατών

Μια εφαρμογή συνεργάτη, ένα εργαλείο αυτοματισμού ή μια προσαρμοσμένη εφαρμογή που εργάζεται για έναν χρήστη του MonoChat μπορεί να καλεί το API προσαρμοσμένων συναρτήσεων (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) με ένα access token OAuth αντί για API token. Ο χρήστης εγκρίνει την εφαρμογή σε μια σελίδα του MonoChat, επιλέγει τους χώρους εργασίας στους οποίους μπορεί να έχει πρόσβαση και μπορεί να την ανακαλέσει ανά πάσα στιγμή στις Συνδεδεμένες εφαρμογές στις ρυθμίσεις προφίλ του.

Τα API tokens συνεχίζουν να λειτουργούν στο ίδιο endpoint. Το OAuth είναι η επιλογή για μια εφαρμογή που ενεργεί για λογαριασμό άλλων ανθρώπων: δεν βλέπει ποτέ κωδικό πρόσβασης ή API token, και κάθε χρήστης μπορεί να διακόψει την πρόσβασή της μόνος του.

Η εφαρμογή ενεργεί ως ο χρήστης

Μια κλήση που γίνεται με access token εκτελείται ως ο χρήστης που ενέκρινε την εφαρμογή, με τους ρόλους αυτού του χρήστη. Εκτελεί μόνο τις προσαρμοσμένες μεθόδους του χώρου εργασίας, και μόνο σε χώρους εργασίας όπου ο χρήστης είναι εκπρόσωπος.

Απόκτηση client​

Ζητήστε από το MonoChat έναν client για την εφαρμογή σας. Το MonoChat τον καταχωρίζει με:

  • το όνομα της εφαρμογής, που εμφανίζεται στη σελίδα έγκρισης και στις Συνδεδεμένες εφαρμογές·
  • τα redirect URI της, που πρέπει να ταιριάζουν ακριβώς: διευθύνσεις https, ή http σε localhost, 127.0.0.1 ή [::1] (οποιαδήποτε θύρα)·
  • τα scopes που μπορεί να ζητήσει: custom-functions:run για αυτό το API.

Λαμβάνετε ένα client ID (ξεκινά με monochat_rc_) και ένα client secret (ξεκινά με monochat_cs_). Το secret εμφανίζεται μία φορά· το MonoChat αποθηκεύει μόνο το hash του. Κρατήστε το στον διακομιστή σας, ποτέ σε πρόγραμμα περιήγησης ή σε εφαρμογή για κινητά.

Μια εφαρμογή που δεν μπορεί να κρατήσει ένα secret, όπως μια εφαρμογή που εκτελείται στο πρόγραμμα περιήγησης ή στον υπολογιστή του χρήστη, μπορεί αντί γι' αυτό να χρησιμοποιήσει ως client ID το URL ενός εγγράφου μεταδεδομένων client ID, όπως κάνουν οι πελάτες MCP. Τότε δεν στέλνει secret.

Endpoints​

Τα μεταδεδομένα του διακομιστή εξουσιοδότησης στο https://app.monochat.ai/.well-known/oauth-authorization-server απαριθμούν κάθε endpoint. Σε εγκατάσταση white-label ή self-hosted, χρησιμοποιήστε τη δική της διεύθυνση.

ΡύθμισηΤιμή
Endpoint εξουσιοδότησηςhttps://app.monochat.ai/oauth/authorize
Endpoint tokenhttps://app.monochat.ai/oauth/token
Endpoint ανάκλησηςhttps://app.monochat.ai/oauth/revoke
Πόροςhttps://app.monochat.ai/api/custom-functions
Scopecustom-functions:run
Έλεγχος ταυτότητας clientHTTP Basic, ή client_id και client_secret στο σώμα του αιτήματος

Τα μεταδεδομένα του ίδιου του πόρου βρίσκονται στο https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions.

Σύνδεση ενός χρήστη​

Το MonoChat χρησιμοποιεί τη ροή authorization code με PKCE (S256). Ο χρήστης πρέπει να έχει ρυθμίσει επαλήθευση δύο βημάτων (με e-mail ή με εφαρμογή ελέγχου ταυτότητας).

  1. Στείλτε τον χρήστη στο endpoint εξουσιοδότησης με response_type=code, το client_id σας, ένα redirect_uri που έχετε καταχωρίσει, scope=custom-functions:run, resource=https://app.monochat.ai/api/custom-functions, ένα state και ένα code_challenge με code_challenge_method=S256.
  2. Ο χρήστης συνδέεται στο MonoChat αν χρειάζεται. Η σελίδα έγκρισης αναφέρει την εφαρμογή σας και εμφανίζει Εκτέλεση προσαρμοσμένων μεθόδων για λογαριασμό σας. Ο χρήστης μπορεί να επιλέξει τους Χώρους εργασίας στους οποίους έχει πρόσβαση η εφαρμογή (όλους τους δικούς του όταν δεν επιλεγεί κανένας), εισάγει τον 6ψήφιο κωδικό επιβεβαίωσης και κάνει κλικ στο Να επιτραπεί.
  3. Το MonoChat στέλνει τον χρήστη πίσω στο redirect_uri σας με code, state και iss. Αν ο χρήστης κάνει κλικ στο Απόρριψη, στέλνει αντί γι' αυτό error=access_denied.
  4. Ανταλλάξτε τον κωδικό στο endpoint token μέσα σε 5 λεπτά:
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>

Η απάντηση περιέχει ένα access_token (ξεκινά με monochat_at_) που ισχύει για expires_in δευτερόλεπτα (μία ώρα), ένα refresh_token (ξεκινά με monochat_rt_) και το scope που παραχωρήθηκε.

Κλήση του API​

Στείλτε το access token ως bearer token:

curl -X POST https://app.monochat.ai/api/<slug>/custom-functions/<path> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
ΚατάστασηΠότε
401Το token είναι άγνωστο, έχει λήξει ή έχει ανακληθεί, ή εκδόθηκε για άλλον πόρο, όπως ο διακομιστής MCP. Η κεφαλίδα WWW-Authenticate παραπέμπει στα μεταδεδομένα του πόρου.
403Ο χώρος εργασίας δεν είναι ένας από αυτούς που επέτρεψε ο χρήστης για την εφαρμογή, ο χρήστης δεν έχει πρόσβαση στον χώρο εργασίας, ή η παραχώρηση δεν περιλαμβάνει το custom-functions:run.
429Έχει εξαντληθεί ένα όριο· περιμένετε τα δευτερόλεπτα που αναφέρει το Retry-After. Οι κλήσεις μετρώνται ανά λεπτό: 120 ανά παραχώρηση και 1.200 ανά client, πέρα από το δικό του όριο του χώρου εργασίας για αυτό το endpoint.

Ανανέωση και ανάκληση​

  • Ανανέωση: πριν λήξει το access token, καλέστε το endpoint token με grant_type=refresh_token και το refresh_token. Κάθε ανανέωση επιστρέφει νέο refresh token· χρησιμοποιήστε το νέο. Ένα refresh token που χρησιμοποιείται ξανά περισσότερο από ένα λεπτό αφού αντικαταστάθηκε τερματίζει την παραχώρηση.
  • Λήξη: η παραχώρηση τελειώνει 90 ημέρες μετά την τελευταία ανανέωσή της, όταν ο χρήστης την ανακαλέσει στις Συνδεδεμένες εφαρμογές, ή όταν ο χρήστης αλλάξει ή επαναφέρει τον κωδικό πρόσβασής του. Τότε ο χρήστης πρέπει να εγκρίνει ξανά την εφαρμογή.
  • Ανάκληση: για να αποσυνδέσετε έναν χρήστη, στείλτε με POST το access token ή το refresh token στο endpoint ανάκλησης με τον έλεγχο ταυτότητας του client σας:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

Η εκ νέου σύνδεση του ίδιου χρήστη με την εφαρμογή σας αντικαθιστά την προηγούμενη παραχώρησή του.