Zum Hauptinhalt springen

Authentifizierung

Alle RxScale APIs verwenden API-Schlüssel-Authentifizierung. Fügen Sie Ihren API-Schlüssel bei jeder Anfrage im X-API-Key-Header hinzu.

API-Schlüssel-Header

Alternative Public API-Header

Die Public API akzeptiert auch X-RxScale-Authorization als Alternative zu X-API-Key. Dies wird aus Gründen der Abwärtskompatibilität mit bestehenden Integrationen unterstützt.
Sie können denselben API-Schlüssel auch als Bearer-Token im 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_uid angeben, 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.
Beide Anmeldeinformationstypen werden gegen dieselben Berechtigungsstrings geprüft (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 / ein client_secret für Ihre Auth0-Anwendung
  • Die Auth0-Domain, bei der Tokens angefordert werden
  • Die anzufordernden Scopes, passend zu den von Ihrer Integration benötigten Berechtigungen
Scopes allein genügen nicht. Jedes Bearer-Token wird einem Konto in Ihrer Organisation zugeordnet, bevor seine Scopes ausgewertet werden. Bei einer Machine-to-Machine-Anwendung setzt Auth0 den sub-Claim des Tokens auf <client_id>@clients — eine Identität, die durch keine interaktive Anmeldung entsteht. RxScale muss genau diesen sub als Service-Principal in Ihrer Organisation registrieren, wenn die Anwendung eingerichtet wird. Solange das nicht geschehen ist, beantwortet jede Anfrage mit 401:
Das ist Teil des Onboardings durch Ihren Ansprechpartner und lässt sich nicht selbst in Auth0 konfigurieren. Erhalten Sie diese Antwort trotz funktionierender Zugangsdaten, ist der sub des Clients noch nicht registriert — nennen Sie Ihre client_id und bitten Sie darum, sie mit Ihrer Organisation zu verknüpfen.
Fordern Sie ein Access-Token über den OAuth-2.0-Client-Credentials-Grant an:
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.
Verwenden Sie das zurückgegebene access_token als Bearer-Token:
Die audience für die Management-REST-API ist die API-Wurzel, https://api.rxscale.com/v1/management — kein spezifischer Endpoint-Pfad. Ein Token, das für eine andere Audience ausgestellt wurde, wird mit 401 abgelehnt.

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:write tragen, 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 unter https://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)

  1. Melden Sie sich im Admin Tool an
  2. Navigieren Sie zu Einstellungen → API-Schlüssel
  3. Klicken Sie auf API-Schlüssel erstellen
  4. Geben Sie einen Anzeigenamen für den Schlüssel ein
  5. Wählen Sie die gewünschten Berechtigungen (z.B. order:read, telemed_product:read, prescription:read)
  6. Klicken Sie auf Erstellen — der Schlüssel wird einmalig angezeigt. Kopieren und sicher speichern.
Der API-Schlüssel wird nur einmal bei der Erstellung angezeigt. Wenn Sie ihn verlieren, müssen Sie einen neuen erstellen.

Als Apotheker (External Pharmacy API)

  1. Melden Sie sich im Apotheken-Tool an
  2. Navigieren Sie zu Einstellungen → API-Schlüssel
  3. Erstellen Sie einen neuen Schlüssel für Ihre Apotheke oder Apothekengruppe
  4. 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:
Aus Sicherheitsgründen gibt RxScale 404 Not Found anstelle von 403 Forbidden zurück, wenn Sie versuchen, auf eine Ressource außerhalb Ihres Bereichs zuzugreifen. Dies verhindert die Aufzählung von Ressourcen.
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.