Authentifizierung

Zugriff im Namen einer Person

Der hier beschriebene API-Key gehört Ihrem Unternehmen und lässt sich nicht einschränken. Soll ein Zugriff dagegen im Namen einer einzelnen Person erfolgen – etwa durch einen KI-Agenten – und auf einzelne Fähigkeiten beschränkt sein, verwenden Sie stattdessen persönliche Zugriffstokens.

Für die externe Authentifizierung kann ein im integrierenden System generierter Access-Token eingesetzt werden. Berechnen Sie diesen Access-Token direkt auf Ihrem Server und nicht in JavaScript, damit der API-Key Ihres Unternehmens nicht abgefangen werden kann.

Authentifizierung mittels API-Key

Die Authentifizierung mittels API-Key und Access-Token ist einfach: Im Unternehmensprofil unter API-Integration ist im Feld API-Key ein Schlüssel hinterlegt. Dieser Schlüssel ist ausschließlich MEMOIO und Ihrer Anwendung bekannt. Soll ein Aufruf authentifiziert werden, so wird aus dem Schlüssel durch eine Hash-Funktion ein Access-Token berechnet. Dies wird weiter unten im Detail beschrieben. Die Gegenseite verifiziert den Access-Token, indem sie die gleiche Berechnung ausführt und prüft, ob sie zum selben Ergebnis kommt.

Dasselbe Verfahren gilt in beide Richtungen: Ihr System weist sich damit bei der Nachrichten-API aus, und MEMOIO weist sich damit bei Ihrem Bot, Ihrem Adressbuch und beim Aufruf von Push-URLs aus.

Warum ist dieses Verfahren sicher?

Eine Hash-Funktion ist per definitionem nicht umkehrbar, der API-Key kann also nicht „zurückgerechnet“ werden.
Da der API-Key nur MEMOIO und Ihrer Anwendung bekannt ist, kann ein valider Access-Token nur von diesen Systemen stammen.
Da ein Zeitstempel zur Berechnung des Access-Tokens herangezogen wird, kann ein aufgezeichneter (abgefangener) Token allenfalls für kurze Zeit missbraucht werden.

Wichtig!

Geben Sie den API-Key niemals an Dritte weiter. Zeigen Sie den API-Key niemals in der Oberfläche, in Protokolldateien oder verdeckt – etwa in HTML-Code – an.

Der API-Key ist der Generalschlüssel zu Ihrem Unternehmen auf MEMOIO, womit zu jeder Zeit Zugriff auf sämtliche Services erfolgen kann.

Berechnung des Access-Tokens

Zur Berechnung des Access-Tokens wird das im Unternehmensprofil unter API-Integration eingestellte Hash-Verfahren verwendet. Die folgende Formel berechnet den Access-Token mit SHA256. Die + Operatoren sind dabei als String-Verkettung zu verstehen.

inner = hex(SHA256(key + company + today))
token = hex(SHA256(key + inner))

Die verketteten Zeichenketten werden in UTF-8 kodiert. hex steht für die Darstellung des Hash-Werts als Hexadezimalzahl in Kleinbuchstaben, also als Zeichenkette aus 64 Zeichen 0–9 und a–f. Das gilt sowohl für das Zwischenergebnis inner als auch für den fertigen Access-Token.

Die folgenden Parameter fließen in die Berechnung mit ein:

Parameter	Beschreibung
key	Der API-Key Ihres Unternehmens. Administratoren mit dem Recht „Unternehmen verwalten“ finden ihn im Unternehmensprofil unter API-Integration; die Seite erscheint, sobald Ihr Unternehmen die Nachrichten-API, die Bot-API oder die Adressbuch-API gebucht hat. Einen neuen API-Key vergibt unser Support.
company	Die ID Ihres Unternehmens auf MEMOIO. Sie steht im Unternehmensprofil unter Details im Feld ID.
today	Ein UNIX-Timestamp, auf ganze Tage abgerundet. Der Timestamp in Sekunden wird ganzzahlig durch 86400 (Anzahl der Sekunden pro Tag) dividiert. Das Ergebnis ist die Anzahl der seit dem 1. Januar 1970 vergangenen Tage, gezählt nach UTC. In Java lautet die Berechnung `System.currentTimeMillis() / 1000 / 86400`. Beachten Sie, dass es sich um eine ganzzahlige Division handelt; das Ergebnis wird also abgerundet. Der Wert für den heutigen Tag ist `20771`. Der today-Wert verhindert, dass ein abgefangener Access-Token unbegrenzt weiterverwendet werden kann.

Gültigkeit

MEMOIO akzeptiert einen Access-Token, der mit dem today-Wert des Vortags, des aktuellen Tags oder des Folgetags berechnet wurde. Ein Token bleibt damit bis zum Ende des Folgetags (UTC) gültig, und kleine Abweichungen der Uhrzeit zwischen den Systemen sind unschädlich.

Übertragung des Access-Tokens

Bei einem Aufruf von MEMOIO gehören zu jeder Anfrage zwei Angaben:

Der Parameter companyId mit der ID Ihres Unternehmens. Er ist Pflicht, denn erst über ihn ermittelt MEMOIO den API-Key, mit dem der Access-Token geprüft wird.
Der Access-Token im HTTP-Header Authorization, ohne ein Präfix wie Bearer. Ist das nicht möglich, kann er stattdessen im Parameter key übertragen werden. Davon raten wir ab: Als Teil der URL kann der Access-Token in Protokolldateien und im Browserverlauf landen und ist dort bis zum Ende des Folgetags gültig. Ist beides angegeben, gilt der Header.

Ruft MEMOIO umgekehrt Ihren Bot, Ihr Adressbuch oder eine Push-URL auf, so sendet MEMOIO den Access-Token im HTTP-Header Authorization. Ihre Anwendung berechnet den Token selbst und vergleicht ihn mit dem empfangenen Wert.