Space Access Token

Space Access Token ist ein Token, mit dem sich innerhalb eines Space Inhalte lesen und schreiben lassen. Über die CMA lassen sich Inhalte erstellen, ändern und löschen, und auch das Lesen über die CDA sowie Upload werden mit diesem Token aufgerufen. Bei der Ausstellung wird es an genau eine SpaceRole gebunden, und diese Rolle legt fest, was das Token bis wohin tun darf (welche Content Type mit welchen Aktionen bearbeitet werden dürfen).

Anders als das schreibgeschützte Delivery Access Token kann dieses Token auch schreiben. Anders als das Personal Access Token, das an das gesamte Benutzerkonto gebunden ist, ist es dafür auf einen einzelnen Space beschränkt und kann nicht auf Space-Einstellungen, die Organisation, die Kontoebene oder andere Space zugreifen. In der CMA ist Space Access Token eine Unterressource von Space, und der Pfad richtet sich nach /spaces/{spaceId}/space-access-tokens. Ob Sie dieses Token auf einem Server oder in einem offengelegten Client (z. B. für anonymes Schreiben) hinterlegen, richtet sich nach Ihrem Dienst. Da es ein mächtiges Token mit Schreibrechten ist, sichern Sie es, indem Sie die gebundene Rolle passend zum Offenlegungsbereich des Ortes, an dem das Token liegt, eng fassen (siehe Sicherheit: Rollenbindung passend zum Offenlegungsbereich unten).

Ressourcenstruktur

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

{
  "sys": {
    "id": "7WpR4mKq2bTnXfLc8Vd3HsJ9gEyAo",
    "type": "SpaceAccessToken",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "user": { "sys": { "id": "3trmXRLdJIqc9GPBbyFYQQwYT32LnU", "type": "Refer", "targetType": "User" } },
    "createdBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-19T02:15:38.472Z",
    "updatedBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-19T02:15:38.472Z",
    "accessToken": "SPCATq8Lm2vK9pXfR1Zt0Nc4Wd6Hg5Ua2Ee9Ck3PoYx8Bj6Hg5Ua2Ee9Ck3Po…",
    "scopes": ["SPACE_ACCESS_TOKEN"]
  },
  "allowedReferrers": [],
  "description": "Server-Token zum Anlegen und Bearbeiten von Produkten im Bekleidungs-Onlineshop",
  "name": "Produkt-Backend-Server"
}

Wichtige Schlüssel:

• sys.id: Der eindeutige Bezeichner des Space Access Token. Er wird in {spaceAccessTokenId} der Pfade für Einzelabruf, Änderung und Löschung eingesetzt.
• sys.space: Der Space, zu dem dieses Token gehört. Das Token funktioniert nur in diesem einen Space.
• sys.accessToken: Der geheime Token-Wert, der bei API-Aufrufen verwendet wird. Er beginnt mit SPCAT, und 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 Space Access Token ist er bei der Ausstellung stets ["SPACE_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. Produkt-Backend-Server).
• 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. Im Beispiel oben ist die Liste leer gelassen, weil dieses Token von einem Server aus aufgerufen wird (zur Schreibweise und zur Prüfung siehe Schreibweise für Origins und Referer-Prüfung).

role (die zu bindende SpaceRole) ist ein Eingabewert, der nur im Rumpf der Erstellungsanfrage gesendet wird, und ist in der Antwortressource nicht enthalten. Die gebundene Rolle wird dem tokeneigenen Benutzer (sys.user in der Antwort) zugewiesen, sodass sie im Abrufergebnis nicht als role-Feld zurückkommt. Der accessToken im Beispiel oben ist ein geheimer Wert und wurde daher durch eine Beispielzeichenkette ersetzt. In Wirklichkeit ist es eine lange, undurchsichtige Zeichenkette, die mit SPCAT beginnt, und auch beim erneuten Abruf nach der Ausstellung wird derselbe Wert zurückgegeben.

Systemeigenschaften (sys)

Jedes Space Access Token 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:

Eingabe nur für den Rumpf der Erstellungsanfrage:

Sicherheit: Rollenbindung passend zum Offenlegungsbereich

Space Access Token ist ein mächtiges Token, das auch schreiben kann. An welche SpaceRole es gebunden wird, ist zugleich die Grenze dessen, was dieses Token tun kann, und seine Sicherheitsgrenze. Ob Sie dieses Token auf einem Server oder in einem offengelegten Client (z. B. für anonymes Schreiben) hinterlegen, richtet sich nach Ihrem Dienst; die Sicherheit ergibt sich nicht daraus, "wo Sie es verstecken", sondern daraus, die gebundene Rolle passend zum Offenlegungsbereich eng zu fassen.

• In role der Erstellungsanfrage tragen Sie die sys.id einer engen SpaceRole ein, die nur die für diesen Zweck nötigen Aktionen erlaubt. Bei einem Server-Token zum Anlegen von Produkten binden Sie eine Rolle, die nur Lesen und Schreiben des Produkt-Content Type erlaubt; bei einem öffentlichen Token für anonymes Schreiben eine Rolle, die nur das Erstellen (create) des Beitrags-Content Type erlaubt. Binden Sie also so minimal wie möglich, passend zum Offenlegungsbereich.
• Je stärker ein Token in einem öffentlichen Client offengelegt wird, desto enger fassen Sie die Rolle. Erlauben Sie nur so viel, wie Sie verkraften können, falls das Token nach außen gelangt. Binden Sie die Rolle Administrator oder weitreichende Schreibrollen nicht an öffentliche Token. Verwenden Sie außerdem nicht achtlos den ersten Eintrag aus der SpaceRole-Liste, sondern geben Sie ausdrücklich die sys.id der beabsichtigten engen Rolle an.
• Wird dieses Token aus dem Browser aufgerufen, fassen Sie mit allowedReferrers auch die Aufrufstelle eng. Die gebundene Rolle legt fest, was mit diesem Token möglich ist, und diese Liste legt fest, von wo aus es aufgerufen werden darf (siehe Referer-Prüfung).
• Für die schreibgeschützte Auslieferung, die Besuchern offengelegt wird, eignet sich das Delivery Access Token ohne Schreibrechte besser. Verwenden Sie Space Access Token nur, wenn Schreiben nötig ist, und fassen Sie dessen Rolle passend zum Offenlegungsbereich eng.
• accessToken ist ein geheimer Wert, der auch nach der Ausstellung mit demselben Wert abgerufen wird. Hinterlassen Sie ihn dort, wo er nicht offengelegt werden muss, nicht im Klartext in Code, Protokollen, Speichern oder Fehlermeldungen; bei Verdacht auf Offenlegung machen Sie ihn durch Löschen unwirksam und ersetzen ihn durch ein neues Token.

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 nicht vorhandenen Rolle ein, 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.
• Space Access Token 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_SPACE_ACCESS_TOKEN im settings der Rolle des Aufrufers enthalten sein. Das ist eine andere Aktion als SETTING_DELIVERY_ACCESS_TOKEN, mit dem das schreibgeschützte Delivery Access Token ausgestellt wird; Sie können also die Berechtigung zum Ausstellen von Auslieferungs-Token erteilen und das Ausstellen dieses Tokens dennoch verhindern (siehe SpaceRole).
• Diese API wird nur über eine Anmeldesitzung in der Konsole und über ein Personal Access Token aufgerufen. Mit einem Space Access Token selbst lässt sich kein weiteres Space Access Token erstellen, und daran ändert sich auch nichts, wenn die gebundene Rolle SETTING_SPACE_ACCESS_TOKEN enthält.

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 API 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. Für ein Token, das an einer Stelle zum Einsatz kommt, die keinen Referer sendet, etwa bei Aufrufen zwischen Servern, 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. Ob Sie einen CMA- oder einen CDA-Pfad 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 Space Access Token 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 Space Access Token ist kein X-Weegloo-Version-Header erforderlich.

Verwandte Dokumente

• SpaceRole: Definiert die an dieses Token zu bindende Rolle (Lese- und Schreibbereich).
• Delivery Access Token: Schreibgeschütztes Auslieferungstoken, das Besuchern offengelegt wird (für den Client).
• Personal Access Token: Weegloo-User-Token für Server und CI, das an das gesamte Konto gebunden ist.
• Tarife: Ausstellungsobergrenze für Space Access Token je Tarif.