Authentifizierung

Jede Anfrage an /api trägt ihre Identität im Header Authorization. Das Backend kennt zwei Verfahren.

API-Schlüssel (empfohlen für Integrationen)

Ein API-Schlüssel besteht aus Schlüssel und Geheimnis und wird als HTTP-Basic-Anmeldung gesendet: Schlüssel als Benutzername, Geheimnis als Passwort.

curl -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  https://app.apptivegrid.de/api/users/me

Ausgeschrieben ist das der Header

Authorization: Basic base64(schlüssel:geheimnis)

Schlüssel erzeugen

In der Anwendung unter Profil & Einstellungen → API Zugangsdaten (https://app.apptivegrid.de/settings/credentials). Zur Auswahl stehen zwei Rollen:

Auswahl in der Oberfläche	Rolle in der API	Wirkung
Admin	admin	Voller Zugriff auf alle Spaces des Kontos
Nur lesen	reader	Lesezugriff auf alle Spaces des Kontos

Das Geheimnis wird genau einmal angezeigt

Nach dem Schließen des Dialogs lässt es sich nicht wieder abrufen. Ist es verloren, löschen Sie den Schlüssel und erzeugen einen neuen.

Derselbe Vorgang über die API — er setzt eine bestehende Anmeldung voraus:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Buchhaltungs-Import", "role": "reader"}' \
  https://app.apptivegrid.de/api/users/$USER_ID/accessKeys

Antwort:

{ "key": "…", "secret": "…", "name": "Buchhaltungs-Import" }

role akzeptiert ausschließlich reader oder admin; jeder andere Wert ergibt 400.

Vorhandene Schlüssel auflisten und löschen:

curl -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  https://app.apptivegrid.de/api/users/$USER_ID/accessKeys

curl -X DELETE -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  https://app.apptivegrid.de/api/users/$USER_ID/accessKeys/$KEY_ID

Das Geheimnis erscheint in der Liste nicht.

Bearer-Token

Das Zugriffstoken aus der Anmeldung der Weboberfläche wird als JWT geschickt:

Authorization: Bearer <token>

Das ist das Verfahren des Frontends. Für Server-zu-Server-Integrationen ist der API-Schlüssel der einfachere Weg, weil er nicht abläuft.

Ohne Authorization gibt es fast nichts zu sehen

Fehlt der Header, behandelt das Backend die Anfrage als nicht autorisiert; alles unterhalb von /api/users antwortet dann mit 401.

Drei Ausnahmen sind bewusst offen:

• die öffentlichen Links unter /api/a/… und /api/r/…,
• die Metadaten-Endpunkte GET /api/types, /api/nodeTypes, /api/blocks und /api/version,
• GET /api/users/me, das ohne Zugangsdaten allerdings 401 liefert, weil es die Identität ja gerade auflösen soll.

Die eigene Benutzerkennung finden

Fast alle Pfade beginnen mit /api/users/{userId}. Die eigene Kennung liefert eine Weiterleitung:

curl -i -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  https://app.apptivegrid.de/api/users/me

HTTP/1.1 302 Found
Location: /api/users/64f1a2b3c4d5e6f708091a2b

Der Kennung folgen — curl -L — liefert die Benutzerressource mit allen weiterführenden _links.

Rollen und Berechtigungen

Jede Operation ist im Backend an eine benannte Berechtigung gebunden, und jede Berechtigung nennt die Rollen, die sie ausüben dürfen. Es gibt vier Rollen:

Rolle	Darf
reader	Lesen
writer	Lesen und Daten ändern
admin	Alles, einschließlich Struktur ändern und freigeben
creator	Nur anlegen — kommt bei addEntity vor und erlaubt das Einreichen von Einträgen ohne Leserecht

Welche Rolle für einen konkreten Endpunkt reicht, steht bei jedem Endpunkt in der OpenAPI-Beschreibung unter x-apptivegrid-roles sowie in der Endpunkt-Referenz.

Ein paar Regelmäßigkeiten, die das Bild ordnen:

• Struktur ändern — Space, Grid, Feld, Ansicht anlegen oder löschen, freigeben — verlangt durchgehend admin.
• Einträge lesen genügt reader, Einträge ändern verlangt writer.
• Wer keine Rolle auf der Ressource hat, bekommt 403, nicht 404.

Rechte stehen in der Antwort

Statt Rollen nachzubilden, prüfen Sie _links der Ressource: nur erlaubte Operationen erscheinen dort. → Überblick

Woher eine Identität ihre Rollen bekommt

• Der Kontoinhaber ist Administrator seiner eigenen Spaces.
• Eine Space-Freigabe (POST …/spaces/{spaceId}/shares mit email und role) gibt einer anderen Person eine Rolle in diesem Space.
• Ein API-Schlüssel trägt die Rolle, die bei seiner Erzeugung gewählt wurde, und wirkt auf alle Spaces des Kontos.
• Ein öffentlicher Link kann eine Rolle mitbringen, ohne dass sich jemand anmeldet.

Öffentliche Links ohne Anmeldung

Formulare, geteilte Ansichten und Bearbeitungslinks liegen unter /api/a/… und /api/r/… und sind bewusst ohne Konto erreichbar. Ein Link kann zusätzlich geschützt sein:

Antwort	Bedeutung
401 mit Apptive-Authorization: link	Der Link verlangt Benutzername und Passwort. Diese als HTTP-Basic senden.
401 mit Apptive-Authorization: internal	Der Link verlangt eine angemeldete ApptiveGrid-Identität.

# Ein mit Passwort geschützter Ansichtslink
curl -u "linkbenutzer:linkpasswort" \
  https://app.apptivegrid.de/api/a/$USER_ID/$LINK_ID

Der Header Apptive-Authorization erscheint nur bei 401 und sagt, welche Art von Anmeldung erwartet wird.