Authentifizierung
Alle RxScale APIs verwenden API-Schlüssel-Authentifizierung. Fügen Sie Ihren API-Schlüssel bei jeder Anfrage imX-API-Key-Header hinzu.
API-Schlüssel-Header
Alternative Public API-Header
Die Public API akzeptiert auchX-RxScale-Authorization als Alternative zu X-API-Key. Dies wird aus Gründen der Abwärtskompatibilität mit bestehenden Integrationen unterstützt.
Authorization-Header senden.
Neue Integrationen sollten
X-API-Key verwenden, sofern Ihre Plattform keine
Bearer-Token-Authentifizierung erfordert. Die Header X-RxScale-Authorization
und Authorization: Bearer werden nur auf Public API-Endpoints unterstützt.API-Schlüssel-Typen
Pharmacy API-Schlüssel
Pharmacy API-Schlüssel können auf folgende Bereiche beschränkt werden:- Eine einzelne Apotheke — Der Schlüssel kann nur auf Daten dieser bestimmten Apotheke zugreifen. Wird diese Apotheke entfernt, ist der Schlüssel nicht mehr gültig und jede Anfrage liefert
401. - Eine Apothekengruppe — Der Schlüssel kann auf Daten aller Apotheken in der Gruppe zugreifen. Bei Verwendung eines gruppenweiten Schlüssels müssen Sie den Query-Parameter
pharmacy_uidangeben, um festzulegen, für welche Apotheke Sie handeln.
Management API-Schlüssel
Management API-Schlüssel sind auf eine Organisation beschränkt. Sie können auf Daten aller Entitäten innerhalb dieser Organisation zugreifen.Management API: API-Schlüssel oder OAuth-Bearer-Token
Jeder Management-API-Endpoint — einschließlich des MCP-Endpoints — akzeptiert eine der beiden folgenden Anmeldeinformationen:X-API-Key— der oben beschriebene, organisationsweite API-Schlüssel.Authorization: Bearer <token>— ein OAuth-2.0-Access-Token, ausgestellt vom Auth0-Tenant von RxScale.
order:read, product:write, questionnaire:read, …). Die Berechtigungen eines API-Schlüssels werden bei dessen Erstellung festgelegt; die Berechtigungen eines Bearer-Tokens ergeben sich aus dessen OAuth-scope- (oder Auth0-RBAC-permissions-) Claim.
Senden Sie
X-API-Key oder Authorization: Bearer, nicht beides. Ist X-API-Key vorhanden, hat er Vorrang und die Anfrage wird als API-Schlüssel authentifiziert.Ein Bearer-Token erhalten
RxScale richtet die Auth0-Anwendung für Ihre Integration im Rahmen des Onboardings ein — Sie registrieren keinen eigenen Auth0-Tenant oder -Client und fügen niemals einen API-Schlüssel in eine OAuth-Client-Konfiguration ein. Wenden Sie sich an Ihren RxScale-Ansprechpartner, um Folgendes zu erhalten:- Eine
client_id/ einclient_secretfür Ihre Auth0-Anwendung - Die Auth0-Domain, bei der Tokens angefordert werden
- Die anzufordernden Scopes, passend zu den von Ihrer Integration benötigten Berechtigungen
scope ist eine durch Leerzeichen getrennte Liste der Berechtigungs-Strings, die Ihre
Integration benötigt (dieselben Strings wie bei API-Schlüsseln, z.B. order:read,
product:write). Fordern Sie nur die tatsächlich genutzten Scopes an — Auth0 lehnt
einen Scope ab, für den Ihr Client nicht registriert ist, und ein zu weit gefasster
Grant ist unnötige Exposition, falls das Token abhandenkommt.access_token als Bearer-Token:
Die beiden Anmeldeinformationstypen führen ihre Berechtigungen unabhängig voneinander
Beide Anmeldeinformationen werden gegen dieselben Berechtigungsstrings geprüft, teilen sich aber keinen Berechtigungsspeicher — und keine der beiden begrenzt die andere:
Drei Konsequenzen, die Sie einplanen sollten:
- Die Scopes eines Bearer-Tokens werden nicht durch Ihre API-Schlüssel eingeschränkt. Ein Token kann
product:writetragen, auch wenn kein API-Schlüssel Ihrer Organisation diese Berechtigung besitzt. Scopes werden je Auth0-Anwendung vergeben und danach nicht gegen die Berechtigungen Ihrer Schlüssel gefiltert. - Das Entfernen einer Berechtigung von einem API-Schlüssel wirkt sich nicht auf Bearer-Tokens aus — und das Reduzieren der Scopes einer Auth0-Anwendung nicht auf API-Schlüssel. Das sind zwei getrennte Widerrufe; fordern Sie beide an, wenn der Zugriff einer Integration eingeschränkt werden soll.
- Eine Änderung der Scopes einer Auth0-Anwendung verkürzt kein bereits ausgestelltes Token. Access-Tokens sind in sich abgeschlossen und werden bis zu ihrem Ablauf akzeptiert.
Eine kompromittierte Integration sofort abschalten. Da jedes Bearer-Token bei
jeder Anfrage einem Service-Principal Ihrer Organisation zugeordnet wird, stoppt das
Entfernen dieses Service-Principals sämtliche Tokens dieser Anwendung auf einmal —
auch bereits ausgestellte, ohne deren Ablauf abzuwarten. Das ist, zusammen mit dem
Rotieren des
client_secret, der schnellste Weg zur Eindämmung; fordern Sie beides bei
Ihrem RxScale-Ansprechpartner an.Welchen 401 Sie vor sich haben
Beide folgenden Fehler antworten mit 401, haben aber unterschiedliche Ursachen:
Der MCP-Endpoint verwendet eine eigene Audience
Die Management API bietet außerdem einen MCP-Endpoint (Model Context Protocol) für KI-Clients wie Cursor oder Claude Desktop, erreichbar unterhttps://api.rxscale.com/v1/management/mcp. Er liefert dieselben Organisationsdaten über eine kuratierte Menge an Tools, aber seine Bearer-Tokens werden für eine andere, separat registrierte Auth0-Audience ausgestellt — die eigene URL des MCP-Endpoints, nicht die oben genannte REST-API-Wurzel. Ein für eine Audience ausgestelltes Token wird bei der jeweils anderen abgelehnt. Details zur Verbindung finden Sie im Management-API-MCP-Leitfaden.
Berechtigungen
Jeder API-Schlüssel verfügt über eine Reihe von Berechtigungen, die steuern, auf welche Endpoints zugegriffen werden kann. Häufige Berechtigungen sind:API-Schlüssel erstellen
Als Admin (Management API & Public API)
- Melden Sie sich im Admin Tool an
- Navigieren Sie zu Einstellungen → API-Schlüssel
- Klicken Sie auf API-Schlüssel erstellen
- Geben Sie einen Anzeigenamen für den Schlüssel ein
- Wählen Sie die gewünschten Berechtigungen (z.B.
order:read,telemed_product:read,prescription:read) - Klicken Sie auf Erstellen — der Schlüssel wird einmalig angezeigt. Kopieren und sicher speichern.
Als Apotheker (External Pharmacy API)
- Melden Sie sich im Apotheken-Tool an
- Navigieren Sie zu Einstellungen → API-Schlüssel
- Erstellen Sie einen neuen Schlüssel für Ihre Apotheke oder Apothekengruppe
- Wählen Sie die benötigten Berechtigungen (z.B.
orders_read,orders_write,stock_read)
Apotheken-API-Schlüssel können auf eine einzelne Apotheke beschränkt oder für eine gesamte Apothekengruppe gültig sein. Gruppenweite Schlüssel erfordern den Parameter
pharmacy_uid bei jeder Anfrage.Fehlerantworten
Wenn die Authentifizierung fehlschlägt, erhalten Sie eine der folgenden Antworten:Anfragen, die wegen eines falschen Geheimnisses zu einem Ihrer API-Schlüssel (
401) oder
einer fehlenden Berechtigung (403) abgelehnt werden, werden im
Audit-Log Ihrer Organisation festgehalten.