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 token | https://app.monochat.ai/oauth/token |
| Endpoint ανάκλησης | https://app.monochat.ai/oauth/revoke |
| Πόρος | https://app.monochat.ai/api/custom-functions |
| Scope | custom-functions:run |
| Έλεγχος ταυτότητας client | HTTP Basic, ή client_id και client_secret στο σώμα του αιτήματος |
Τα μεταδεδομένα του ίδιου του πόρου βρίσκονται στο https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions.
Σύνδεση ενός χρήστη
Το MonoChat χρησιμοποιεί τη ροή authorization code με PKCE (S256). Ο χρήστης πρέπει να έχει ρυθμίσει επαλήθευση δύο βημάτων (με e-mail ή με εφαρμογή ελέγχου ταυτότητας).
- Στείλτε τον χρήστη στο 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. - Ο χρήστης συνδέεται στο MonoChat αν χρειάζεται. Η σελίδα έγκρισης αναφέρει την εφαρμογή σας και εμφανίζει Εκτέλεση προσαρμοσμένων μεθόδων για λογαριασμό σας. Ο χρήστης μπορεί να επιλέξει τους Χώρους εργασίας στους οποίους έχει πρόσβαση η εφαρμογή ( όλους τους δικούς του όταν δεν επιλεγεί κανένας), εισάγει τον 6ψήφιο κωδικό επιβεβαίωσης και κάνει κλικ στο Να επιτραπεί.
- Το MonoChat στέλνει τον χρήστη πίσω στο
redirect_uriσας μεcode,stateκαιiss. Αν ο χρήστης κάνει κλικ στο Απόρριψη, στέλνει αντί γι' αυτόerror=access_denied. - Ανταλλάξτε τον κωδικό στο 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>
Η εκ νέου σύνδεση του ίδιου χρήστη με την εφαρμογή σας αντικαθιστά την προηγούμενη παραχώρησή του.