Αναφορά API / Αυθεντικοποίηση

Τα bearer tokens, αναλυτικά

Κάθε αίτημα με ταυτοποίηση στο API του HyperCRM φέρει μία κεφαλίδα: `Authorization: Bearer <token>`. Αυτή η σελίδα καλύπτει ακριβώς τι μπορεί να είναι αυτό το token, πώς απορρίπτεται μια κακοσχηματισμένη ή άκυρη κεφαλίδα, και τον συγκεκριμένο κωδικό σφάλματος για κάθε περίπτωση αποτυχίας.

Η κεφαλίδα

Κάθε endpoint απαιτεί Authorization: Bearer <token>. Τα REST endpoints κάτω από το /api/v1 δέχονται ένα Firebase ID token από μια συνδεδεμένη συνεδρία HyperCRM. Το endpoint MCP (/api/v1/mcp) δέχεται επιπλέον ένα αδιαφανές OAuth access token (hcrm_at_...) που εκδίδεται από τον δικό του διακομιστή εξουσιοδότησης OAuth 2.1 του HyperCRM. Εκεί, ένα token που ξεκινά με hcrm_at_ ελέγχεται ως OAuth token, και οτιδήποτε άλλο επαληθεύεται ως Firebase ID token. Μια κλήση REST με token hcrm_at_ απορρίπτεται με 401.

Χωρίς ξεχωριστό βήμα εγγραφής

Δεν υπάρχει πίνακας API-key ούτε endpoint εγγραφής για έναν καλούντα αυθεντικοποιημένο με Firebase. Στην πρώτη επιτυχή επαλήθευση μιας δεδομένης ταυτότητας Firebase, το HyperCRM βρίσκει ή δημιουργεί τον αντίστοιχο χρήστη. Ένας πρωτοεμφανιζόμενος καλών χωρίς ιατρείο και χωρίς εκκρεμή πρόσκληση αποκτά νέο ιατρείο με τον ίδιο ως ιδιοκτήτη· ένα προσκεκλημένο μέλος εντάσσεται στο ιατρείο που το προσκάλεσε, ως προσωπικό. Κάθε επόμενη κλήση επιλύει το ίδιο ιατρείο από το token, και ένα αίτημα ποτέ δεν προμηθεύει το δικό του practiceId.

OAuth access tokens

Για πελάτες MCP, το HyperCRM εκδίδει τα δικά του αδιαφανή access tokens hcrm_at_... και refresh tokens hcrm_rt_... μέσω μιας συμβατής με πρότυπα ροής OAuth 2.1: δυναμική εγγραφή πελάτη, μια οθόνη συναίνεσης βασισμένη στην ίδια σύνδεση Firebase, και υποχρεωτική ανταλλαγή κωδικού εξουσιοδότησης PKCE (S256). Τα tokens δεν είναι ποτέ JWT, αποθηκεύεται μόνο το SHA-256 hash τους, και ένα refresh token περιστρέφεται σε κάθε χρήση, ακυρώνοντας το προηγούμενο.

Τα access tokens λήγουν μετά από μία ώρα. Ένα refresh token που δεν χρησιμοποιείται για 30 ημέρες λήγει, και καμία αλυσίδα δεν ζει πάνω από 90 ημέρες από την έγκριση, και μια αλυσίδα τελειώνει νωρίτερα σε επαναφορά κωδικού, αλλαγή email, αφαίρεση από το ιατρείο ή αποσύνδεση. Η έγκριση ενός πελάτη χρειάζεται σύνδεση μέσα στα τελευταία 10 λεπτά (reauth_required, 403), επιβεβαιωμένη διεύθυνση email, και ιατρείο στο Complete.

Όταν αποτυγχάνει η αυθεντικοποίηση

Μια απούσα κεφαλίδα επιστρέφει missing_authorization· μια κεφαλίδα που δεν είναι Bearer <token> επιστρέφει invalid_authorization_header· ένα μη αναλύσιμο ή μη επαληθεύσιμο token επιστρέφει invalid_auth_token ή auth_token_verification_failed. Ένα ληγμένο token επιστρέφει expired_auth_token, και ένα ανακληθέν επιστρέφει revoked_auth_token. Και τα έξι είναι HTTP 401. Ένας απενεργοποιημένος λογαριασμός είναι HTTP 403, όχι 401: το ίδιο το token εξακολουθεί να επαληθεύεται σωστά, αλλά η ταυτότητα πίσω του είναι απενεργοποιημένη, εμφανιζόμενη ως disabled_auth_token ή user_disabled ανάλογα με ποια πλευρά το σημείωσε. Τα unsupported_auth_provider και auth_provider_email_required (και τα δύο 403) καλύπτουν παρόχους σύνδεσης που το HyperCRM δεν υποστηρίζει για πρόσβαση API. Το auth_configuration_missing (503) σημαίνει ότι ο ίδιος ο διακομιστής δεν έχει ρυθμισμένο έργο Firebase.

Το mfa_required (403) σημαίνει ότι το ιατρείο απαιτεί επαλήθευση με passkey, κάτι που ένα bearer token από μόνο του δεν καλύπτει. Το email_not_verified (403) σημαίνει ότι η ενέργεια χρειάζεται επιβεβαιωμένη διεύθυνση email, για παράδειγμα μια εξαγωγή CSV. Το auth_email_conflict (409) σημαίνει ότι μια άλλη ταυτότητα σύνδεσης κατέχει ήδη αυτή τη διεύθυνση. Το session_ended (401) σημαίνει ότι μια συνεδρία σύνδεσης προσωπικού έχει λήξει.

Δείτε την πλήρη αναφορά σφαλμάτων για το πώς αυτοί οι κωδικοί εντάσσονται στον γενικό φάκελο σφάλματος, και τον κόμβο αναφοράς API για τις υπόλοιπες σελίδες πόρων.