DDM HilfeAuthentifizierung
Jede Anfrage trägt einen API-Schlüssel im Header Authorization:
Authorization: Bearer ddm_3f9a1c2b7d4e8f60_Qm9vZ2xlLUtleS1FeGFtcGxlLU5vdC1SZWFsLTEyMzQ1
Schlüssel legt eine Administratorin oder ein Administrator im CMS unter Einstellungen › API-Zugang an.
Einen Schlüssel anlegen
Einstellungen › API-Zugang öffnen
und auf Neuer Schlüssel klicken.
Einen Namen geben
der sagt, welches System ihn benutzt, z. B. PIM-Export. Der Name steht in der Schlüsselliste und im Protokoll.
Wählen, was er darf
- Lesen – Dokumente, Kategorien und Dateien abrufen. Jeder Schlüssel darf lesen.
- Schreiben – Dokumente einspielen, Dokumente und Kategorien ändern und löschen. Ein schreibender Schlüssel braucht eine Push-Quelle (siehe Dokumente einspielen).
Wählen, was er sieht
- Nur freigegebene Inhalte – was Leser in der App sehen: keine archivierten Dokumente, und mit eingeschalteter Verteilung erst nach Freigabe keine unfreigegebenen. Dateien lassen sich nur herunterladen, wenn sie die App verlassen dürfen (Weitergabe erlaubt). Das ist die richtige Wahl für einen Export auf eine Website oder in einen Shop.
- Alles in Dokumente – was die Person im CMS sieht, auch Entwürfe. Ein Schlüssel, der schreibt, sieht immer alles.
Wählen, als wer er handelt
Der Schlüssel hat die Rechte dieser Person: Der Schlüssel einer Administratorin sieht alles, der Schlüssel eines Redakteurs nur die Kategorien, die dieser Redakteur sehen darf. Standardmäßig handelt der Schlüssel als Sie. Für eine Integration ist es oft besser, einen eigenen Benutzer anzulegen, ihm genau die Kategorien zu geben, die die Integration braucht, und den Schlüssel als diesen Benutzer handeln zu lassen.
Bei Bedarf ein Ablaufdatum setzen
Danach funktioniert der Schlüssel nicht mehr.
Den Schlüssel kopieren
Er wird einmal angezeigt. DDM speichert nur einen Fingerabdruck (einen Hash) davon. Niemand kann ihn Ihnen noch einmal zeigen, auch keine Administratorin. Ist er verloren, legen Sie einen neuen an und widerrufen den alten.
Wann ein Schlüssel nicht mehr funktioniert
Eine Anfrage wird mit 401 unauthorized abgewiesen, wenn der Schlüssel fehlt, ungültig oder unbekannt ist, widerrufen oder abgelaufen ist, oder wenn die Organisation abgeschaltet wurde. All das ergibt dieselbe Antwort, damit ein geratener Schlüssel nichts verrät.
Eine Anfrage wird mit 403 forbidden abgewiesen, wenn:
- dem Schlüssel die Berechtigung fehlt (z. B. ein Nur-Lesen-Schlüssel versucht einzuspielen), oder
- die Person, als die er handelt, gesperrt wurde oder die Organisation verlassen hat – der Schlüssel endet mit ihr, oder
- der Tarif der Organisation die API nicht mehr enthält.
Alte CMWS-Schlüssel
Eine Organisation, die aus dem alten Document Distribution Manager umgezogen ist, behält die Schlüssel ihrer CMWS-Schnittstelle. Sie stehen als Alter CMWS-Schlüssel in der Liste, handeln als die beim Umzug genannte Person, schreiben über eine eigene Push-Quelle und gelten nur unter /api/cmws/v1 – siehe Umstieg von CMWS. Sie stehen in der Adresse und damit in vielen Protokollen: Ersetzen Sie einen durch einen neuen Schlüssel, sobald die Anbindung es erlaubt – auch einen neuen nimmt CMWS in ?apikey= an.
Anfragelimit
Ein Schlüssel kann 600 Anfragen pro Minute stellen. Weitere werden mit 429 rate_limited abgewiesen. Der Header Retry-After sagt, wie viele Sekunden zu warten ist.
Schlüssel sicher aufbewahren
- Behandeln Sie einen Schlüssel wie ein Passwort. Er gehört in den Geheimnisspeicher des anderen Systems oder in eine Umgebungsvariable, nie in den Quellcode oder eine URL.
- Nehmen Sie einen Schlüssel pro System, damit das Widerrufen des einen die anderen nicht stoppt.
- Geben Sie einem Schlüssel nicht mehr, als er braucht: Nur-Lesen für einen Export, und eine handelnde Person mit nur den nötigen Kategorien.
- Schlüssel beginnen mit
ddm_. So erkennen Secret-Scanner (etwa der von GitHub) einen veröffentlichten Schlüssel. - Wechseln Sie einen Schlüssel so: einen neuen anlegen, das System umstellen, dann den alten unter Einstellungen › API-Zugang widerrufen. Das Widerrufen wirkt ab der nächsten Anfrage.
Jede Änderung über einen Schlüssel steht im Protokoll, unter der Person, als die der Schlüssel handelt. Auch das Anlegen und Widerrufen von Schlüsseln wird protokolliert.