Delivery Access Token

DeliveryAccessToken ist ein Lese-Token, das beim Lesen von veröffentlichten Inhalten über die CDA (öffentliche Auslieferung) verwendet wird. Wenn der Browser einer Website oder App veröffentlichte Inhalte abruft, ruft er die CDA mit diesem Token auf. Bei der Ausstellung wird das Token an genau eine SpaceRole gebunden, und diese Rolle legt den Lesebereich des Tokens fest (welche Content Type gelesen werden dürfen).

In der CMA ist DeliveryAccessToken eine Unterressource von Space, und der Pfad richtet sich nach /spaces/{spaceId}/delivery-access-tokens. Da dieses Token im Browser (Client) offengelegt betrieben wird, muss die gebundene Rolle zwingend nach dem Prinzip der minimalen Rechte (least-privilege) festgelegt werden, sodass nur die wirklich benötigten Content Type gelesen werden können (siehe Sicherheit: Bindung mit minimalen Rechten unten). Tragen Sie darüber hinaus in allowedReferrers die Origins ein, von denen der Aufruf erlaubt ist, dann lässt sich dieses Token außerhalb der angegebenen Website nicht mehr verwenden (siehe Schreibweise für Origins und Referer-Prüfung).

Ressourcenstruktur

Im Folgenden steht die Antwort beim Erstellen eines DeliveryAccessToken. In sys (Systemeigenschaften) sind der Token-Wert und der Bereich enthalten, im Rumpf stehen name, description und allowedReferrers.

{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7PUFQuOAqWOc",
    "type": "DeliveryAccessToken",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "user": { "sys": { "id": "3trmXRLdJIqc9GPBbyFYQQw6hf9kGj", "type": "Refer", "targetType": "User" } },
    "createdBy": { "sys": { "id": "3trmXRM3RqbgSnifyg7PUFQsSPi0nt", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T09:24:23.156Z",
    "updatedBy": { "sys": { "id": "3trmXRM3RqbgSnifyg7PUFQsSPi0nt", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T09:24:23.156Z",
    "accessToken": "DVRATbQ8mX2vK9pLs7Rf1Zt0Nc4Wd6Hg5Ua2Ee9Ck3PoYx8Bj6Hg5Ua2Ee9Ck3Po…",
    "scopes": ["DELIVERY_ACCESS_TOKEN"]
  },
  "allowedReferrers": ["https://shop.example.com"],
  "description": "Schreibgeschütztes Auslieferungstoken für die öffentliche Website des Bekleidungsshops",
  "name": "Öffentliche Website-Auslieferung"
}

Wichtige Schlüssel:

• sys.id: Der eindeutige Bezeichner des DeliveryAccessToken. Er wird in {deliveryAccessTokenId} der Pfade für Einzelabruf, Änderung und Löschung eingesetzt.
• sys.accessToken: Der geheime Token-Wert, der beim CDA-Aufruf verwendet wird. Da nach der Ausstellung auch beim erneuten Abruf derselbe Wert zurückgegeben wird, ist beim Offenlegen Vorsicht geboten (siehe Sicherheitsabschnitt unten).
• sys.scopes: Der Berechtigungsbereich des Tokens. Bei DeliveryAccessToken ist er bei der Ausstellung stets ["DELIVERY_ACCESS_TOKEN"].
• sys.user: Der dedizierte Benutzer, der das Berechtigungssubjekt dieses Tokens ist. Er wird bei der Ausstellung automatisch erstellt, und die Rechte der gebundenen SpaceRole werden diesem Benutzer erteilt. Die effektiven Rechte des Tokens stammen also von diesem Benutzer. Es handelt sich um einen anderen Benutzer als die Person, die dieses Token tatsächlich ausgestellt hat (sys.createdBy).
• name: Der beim Erstellen festgelegte Token-Name (z. B. Öffentliche Website-Auslieferung).
• description: Eine Beschreibung des Tokens (optional).
• allowedReferrers: Die Liste, die einschränkt, von welchen Origins dieses Token aufgerufen werden darf. Ist die Liste leer, gilt keine Einschränkung. Das Token im Beispiel oben kommt nur durch, wenn der Aufruf von der öffentlichen Website des Bekleidungsshops (https://shop.example.com) erfolgt (zur Schreibweise und zur Prüfung siehe Schreibweise für Origins und Referer-Prüfung).

Der accessToken im Beispiel oben ist ein geheimer Wert und wurde daher durch eine Beispielzeichenkette ersetzt. In Wirklichkeit ist es eine lange, undurchsichtige Zeichenkette, und auch beim erneuten Abruf nach der Ausstellung wird derselbe Wert zurückgegeben.

Systemeigenschaften (sys)

Jedes DeliveryAccessToken fasst die gemeinsamen Systemeigenschaften und die tokenspezifischen Eigenschaften im sys-Objekt zusammen. space, user, createdBy und updatedBy liegen in der Refer-Form vor ({ "sys": { "id", "type": "Refer", "targetType" } }).

Rumpfeigenschaften:

Sicherheit: Bindung mit minimalen Rechten

DeliveryAccessToken ist ein Token, das offengelegt gegenüber Browsern und Besuchern die CDA aufruft. Deshalb bestimmt die Frage, an welche SpaceRole es gebunden wird, unmittelbar die Sicherheitsgrenze dieses Tokens.

• In role der Erstellungsanfrage trägt man die sys.id einer SpaceRole mit minimalen Rechten ein, die nur die benötigten Content Type liest. Für die öffentliche Auslieferung wird eine schreibgeschützte Rolle empfohlen.
• Binden Sie niemals die Rolle Administrator. Da dieses Token im Client offengelegt wird, würden bei Bindung einer Rolle mit Verwaltungsrechten genau diese Rechte unverändert nach außen gelangen. Verwenden Sie außerdem nicht achtlos den ersten Eintrag aus der SpaceRole-Liste, sondern geben Sie ausdrücklich die sys.id der beabsichtigten Rolle mit minimalen Rechten an.
• Mit allowedReferrers binden Sie zusätzlich die Aufrufstelle mit ein, an der dieses Token verwendet werden darf. Die gebundene Rolle legt fest, was mit diesem Token gelesen werden darf, und diese Liste legt fest, von wo aus es aufgerufen werden darf. Bei einem Token, das im Browser läuft, lässt sich der Wert selbst nicht verbergen; tragen Sie daher den Origin der öffentlichen Website in die Liste ein, dann kommt ein CDA-Aufruf außerhalb dieser Website auch dann nicht durch, wenn der Token-Wert nach außen gelangt (siehe Referer-Prüfung).
• accessToken ist ein geheimer Wert, der auch nach der Ausstellung mit demselben Wert abgerufen wird. Schleusen Sie ihn sicher in den Client-Build ein, legen Sie ihn aber nicht unverändert nach außen offen.

Status und Einschränkungen

Wertebeschränkungen, die beim Erstellen und Ändern einzuhalten sind.

Regeln zu Bindung und Berechtigungen:

• Die zu bindende role muss in diesem Space tatsächlich existieren. Tragen Sie die sys.id einer Rolle ein, die es in diesem Space nicht gibt, wird die Erstellung abgelehnt.
• Der Aufrufer kann nur Rollen binden, die er in diesem Space selbst besitzt. Diese Einschränkung verhindert, dass jemand dem Token durch Binden einer Rolle, die er nicht besitzt, höhere Rechte verleiht; eine Erstellungsanfrage, die dagegen verstößt, wird abgelehnt. Der Administrator dieses Space (Inhaber der Administrator-Rolle) unterliegt dieser Einschränkung jedoch nicht und kann jede beliebige Rolle binden.
• DeliveryAccessToken ist eine Ressource mit einer Anzahlobergrenze. Wenn Sie die Ausstellungsobergrenze Ihres aktuellen Tarifs überschreiten, wird die Erstellung abgelehnt. Die Obergrenzen je Tarif finden Sie unter Tarife.
• Für Ausstellung und Verwaltung (Erstellen, Abrufen, Ändern, Löschen) muss SETTING_DELIVERY_ACCESS_TOKEN im settings der Rolle des Aufrufers enthalten sein. Das ist eine andere Aktion als SETTING_SPACE_ACCESS_TOKEN, mit dem das auch schreibfähige Space Access Token ausgestellt wird; Sie können also die Berechtigung zum Ausstellen von Auslieferungs-Token erteilen und das Ausstellen von Schreib-Token dennoch verhindern (siehe SpaceRole).
• Diese API wird nur über eine Anmeldesitzung in der Konsole und über ein Personal Access Token aufgerufen. Mit einem ausgestellten DeliveryAccessToken selbst lässt sich kein weiteres DeliveryAccessToken erstellen.

Schreibweise für Origins

Jeder Eintrag in allowedReferrers ist eine Zeichenkette, die genau einen Origin bezeichnet, von dem der Aufruf erlaubt ist. Tragen Sie ihn in der folgenden Form ein.

"allowedReferrers": [
  "https://shop.example.com",
  "https://*.shop.example.com",
  "http://localhost:3000"
]

Die Liste nimmt höchstens 50 Einträge auf, und derselbe Origin darf nicht zweimal darin stehen. Für jeden Eintrag gelten die folgenden Regeln.

• Als URL-Schema verwenden Sie nur https. http ist nur für localhost, 127.0.0.1 und [::1] erlaubt.
• Eine Wildcard verwenden Sie nur als einzelnes Label *. am Anfang. Im Pfad ist eine Wildcard nicht erlaubt.
• Den Host schreiben Sie in ASCII. Internationalisierte Domains tragen Sie in Punycode-Schreibweise ein.
• Der Port reicht von 1 bis 65535. Lassen Sie ihn weg, gilt der Standardport des URL-Schemas (bei https 443, bei http 80).
• Geben Sie einen Pfad an, kommt die Anfrage nur durch, wenn ihr Pfad genau derselbe ist. Da der Browser den Pfad prozentkodiert sendet, verwenden Sie im Pfad nur ASCII.
• Einträge mit Benutzerinformationen (user@), einer Query (?) oder einem Fragment (#) werden abgelehnt.

Diese Prüfung greift auf allen drei Wegen: beim Erstellen, bei der vollständigen Änderung und bei der Teiländerung. Enthält die Liste auch nur einen Eintrag, der gegen eine Regel verstößt, wird die Liste nicht gespeichert und die Anfrage abgelehnt; einen der fehlerhaften Einträge nennt die Antwort im Fehlergrund (siehe Fehler).

Referer-Prüfung

Rufen Sie nach der Ausstellung mit diesem Token die CDA auf, prüft WEEGLOO bei jeder Anfrage anhand von allowedReferrers, ob die Anfrage durchgelassen wird.

• Ist die Liste leer, gilt keine Einschränkung. Der Aufruf kommt von jedem Origin durch.
• Steht in der Liste auch nur ein Eintrag, entscheidet der Wert des Referer-Headers der Anfrage. Der Origin-Header wird nicht herangezogen.
• Fehlt der Referer-Header oder ist sein Wert leer, wird die Anfrage abgelehnt. Der Browser sendet diesen Header von sich aus; für ein Token, das an einer Stelle zum Einsatz kommt, die keinen Referer sendet, etwa in einem Build-Skript auf dem Server oder beim Server-Rendering, lassen Sie die Liste leer.
• Damit die Anfrage durchkommt, müssen URL-Schema, Host und Port des Referer mit einem Eintrag der Liste alle übereinstimmen. Enthält dieser Eintrag einen Pfad, muss auch der Pfad übereinstimmen.
• https://*.shop.example.com umfasst alle Hosts, die auf .shop.example.com enden, etwa admin.shop.example.com, aber nicht shop.example.com selbst. Wollen Sie beide erlauben, nehmen Sie https://shop.example.com als weiteren Eintrag auf.
• Diese Prüfung gilt für jede Anfrage, die mit diesem Token gesendet wird. Welchen CDA-Pfad Sie aufrufen, ändert daran nichts.
• Eine Anfrage, die diese Prüfung nicht besteht, wird mit HTTP 403 abgelehnt. Den Code, der dabei zurückkommt, finden Sie unter Fehler unten.

Fehler

Dies sind die Codes, die beim Umgang mit einem DeliveryAccessToken auftreten. Codes, die allen Ressourcen gemeinsam sind, finden Sie unter Gemeinsame Fehler.

API

Die Basis-URL aller folgenden Endpunkte ist https://cma.weegloo.com/v1, und im Authorization-Header wird ein Bearer-Token benötigt, das die CMA authentifiziert. Für die Änderung und Teiländerung von DeliveryAccessToken ist kein X-Weegloo-Version-Header erforderlich.

Verwandte Dokumente

• SpaceRole: Definiert die an dieses Token zu bindende Rolle (Lesebereich).
• CDA-Überblick: Die Auslieferungs-API, die mit diesem Token veröffentlichte Inhalte liest.
• Space Access Token: Token, das innerhalb eines Space auch schreiben kann (mit derselben Origin-Einschränkung).
• Personal Access Token: Weegloo-User-Token für Server und CI.