Inhalt

Erste Schritte mit der formcycle REST-API

Diese Anleitung zeigt, wie die Authentifizierung an der formcycle REST-API mit Benutzername und Passwort (formcycle-Systemanmeldung oder LDAP) erfolgt und wie die API über die API-Referenz oder curl genutzt wird.

Für die Nutzung der REST-API ist Folgendes sicherzustellen:

In den Systemeinstellungen im Menüpunkt Allgemein ist unter dem Punkt REST-API die Option für das Aktivieren der REST-API angehakt.

Überblick

API-Referenz aufrufen

Die API-Referenz ist an zwei Stellen verfügbar:

• Auf dem eigenen formcycle-Server unter den unten aufgeführten Adressen. Diese Referenz passt immer genau zur installierten Version.
• Unter docs.formcycle.eu: Dort die eingesetzte formcycle-Version auswählen und den Ordner rest-api öffnen.

Unter docs.formcycle.eu gibt es die REST-API-Dokumentation erst ab formcycle Version 8.5.6

Die API ist in mehrere Bereiche aufgeteilt. In der API-Referenz kann über die API-Auswahl zwischen ihnen gewechselt werden:

Unterstützte Anmeldearten

Für die Anmeldung an der REST-API werden derzeit folgende Login-Dienste unterstützt:

• formcycle-Systemanmeldung
• LDAP

Externe Login-Dienste (z. B. OAuth 2.0, OpenID Connect oder SAML-basierte Dienste wie BundID) können derzeit nicht für die Anmeldung von eigenen Anwendungen an der REST-API verwendet werden.

Schnellstart: In zwei Schritten an die Daten

Das folgende Beispiel zeigt den kompletten Weg von der Anmeldung bis zum Abruf von Daten. Nach diesem Prinzip funktionieren alle geschützten Endpunkte der API. Details zu den einzelnen Schritten (Token erneuern, MFA, Fehlerbehandlung usw.) folgen weiter unten.

Schritt 1: Token anfordern

Mit Benutzername und Passwort wird ein Access Token angefordert. form steht hier für die formcycle-Systemanmeldung (zu LDAP siehe Authentifizierung).

curl -X POST "https://<server>/<context-path>/api/rest/public/security/auth/form/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=<benutzername>" \
  --data-urlencode "password=<passwort>"

Antwort (gekürzt):

{
  "status_type": "SUCCESS",
  "token_response": {
    "access_token": "eyJhbGciOi...",
    "refresh_token": "eyJhbGciOi...",
    "expires_in": 300
  }
}

Benötigt wird der Wert von token_response.access_token. Ist für den Benutzer eine Multi-Faktor-Authentifizierung aktiv, enthält status_type stattdessen den Wert MFA_REQUIRED (siehe Anmeldung mit Multi-Faktor-Authentifizierung).

Schritt 2: Token verwenden

Das Access Token wird bei jedem weiteren Request an geschützte Endpunkte im Authorization-Header mitgeschickt. Im Beispiel wird eine Liste der Vorgänge abgerufen, die der angemeldete Benutzer selbst eingereicht hat:

curl -X GET "https://<server>/<context-path>/api/rest/public/form-records" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"

Nach genau diesem Muster (Token im Header mitschicken, Antwort im JSON-Format auswerten) funktionieren alle geschützten Endpunkte der API. Welche Endpunkte im Detail zur Verfügung stehen, zeigt die API-Referenz.

Authentifizierung (formcycle-Systemanmeldung / LDAP)

Alle geschützten Endpunkte benötigen ein Access Token. Dieses wird über die Security-API mit Benutzername und Passwort angefordert.

Endpunkt:

POST /api/rest/public/security/auth/{clientName}/token

Die Parameter username und password werden als application/x-www-form-urlencoded übertragen. Ein JSON-Body wird nicht unterstützt und mit dem Status 415 Unsupported Media Type abgelehnt.

clientName ermitteln

{clientName} ist der technische Name des Login-Dienstes:

Für LDAP ist nicht ldap anzugeben, sondern die UUID des jeweiligen LDAP-Login-Dienstes. Da mehrere LDAP-Login-Dienste eingerichtet sein können, hat jeder seine eigene UUID.

Die UUID lässt sich auf zwei Wegen ermitteln:

• In der Oberfläche: In den Einstellungen des LDAP-Login-Dienstes im Feld Alias für Callback-URL (UUID).
• Über die REST-API: Ist der LDAP-Login-Dienst einem Benutzerportal zugeordnet, liefert der Endpunkt GET /api/rest/public/user-portals/{userPortalUuid}/authenticators alle Login-Dienste des Portals mit ihrem clientName. Die userPortalUuid liefert GET /api/rest/public/user-portals im Feld uuid (nicht zu verwechseln mit dem Feld alias).

Beispiel-Antwort von /user-portals/{userPortalUuid}/authenticators (gekürzt):

{
  "results": [
    {
      "clientName": "a5c24bf2-8702-4777-b586-cdb6d3e593dd",
      "displayName": "LDAP firma.local",
      "renderType": "FORM_INPUT_USERNAME_PASSWORD"
    },
    {
      "clientName": "form",
      "displayName": "Systemanmeldung",
      "renderType": "FORM_INPUT_USERNAME_PASSWORD"
    }
  ]
}

Beispiel: Token per curl anfordern (formcycle-Systemanmeldung)

curl -X POST "https://<server>/<context-path>/api/rest/public/security/auth/form/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=<benutzername>" \
  --data-urlencode "password=<passwort>"

Beispiel: Token per curl anfordern (LDAP)

curl -X POST "https://<server>/<context-path>/api/rest/public/security/auth/<uuid-des-ldap-login-dienstes>/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=<benutzername>" \
  --data-urlencode "password=<passwort>"

Antwort

{
  "status_type": "SUCCESS",
  "token_response": {
    "access_token": "eyJhbGciOi...",
    "expires_in": 300,
    "refresh_token": "eyJhbGciOi...",
    "refresh_expires_in": 1800,
    "id_token": "eyJhbGciOi...",
    "id_token_expires_in": 3600,
    "token_type": "Bearer"
  }
}

Geschützten Endpunkt aufrufen

Endpunkte, die eine Authentifizierung erfordern, können nur mit einem gültigen Access Token aufgerufen werden. Geschützt sind z. B.:

• die Vorgangs-Endpunkte (siehe https://<server>/<context-path>/api/rest/public/form-records/doc/openapi.html)
• die Endpunkte für das Profil des angemeldeten Benutzers (siehe https://<server>/<context-path>/api/rest/public/users/doc/openapi.html)

Das Access Token wird als Authorization-Header mitgeschickt.

Beispiel:

Im Beispiel werden die Vorgänge abgerufen, die der angemeldete Benutzer selbst eingereicht hat.

Die Vorgangs-Endpunkte liefern ausschließlich Vorgänge aus Sicht des Antragstellers, also Vorgänge, die der angemeldete Benutzer zu irgendeinem Zeitpunkt selbst eingereicht hat. Ein Zugriff auf alle Vorgänge eines Mandanten, wie etwa im Postfach, ist über die REST-API nicht möglich.

curl -X GET "https://<server>/<context-path>/api/rest/public/form-records" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"

Beispiel-Antwort:

{
  "results": [
    {
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "displayName": "Testformular",
      "state": {
        "type": "END_STATE",
        "displayName": "Abgeschlossen"
      },
      "submitTimestamp": 1780307759.981574,
      "applicantName": "Max Mustermann",
      "attachmentCount": 0,
      "chatCount": 0
    }
  ],
  "resultCount": 10,
  "page": 1,
  "pageSize": 10,
  "totalCount": 30,
  "totalPages": 3
}

Listen werden seitenweise ausgeliefert. Über die Query-Parameter page und size lässt sich steuern, welche Seite in welcher Größe geliefert wird, z. B. /form-records?page=2&size=20.

Access Token erneuern

Access Tokens sind nur begrenzt gültig (siehe expires_in). Mit dem Refresh Token lässt sich ein neues Access Token anfordern, ohne Benutzername und Passwort erneut zu übermitteln.

Endpunkt:

POST /api/rest/public/security/auth/{clientName}/token/refresh

Beispiel:

curl -X POST "https://<server>/<context-path>/api/rest/public/security/auth/form/token/refresh" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "refresh_token=<refresh_token>"

Antwort:

Die Antwort enthält die Token direkt, also ohne die Felder status_type und token_response:

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 300,
  "refresh_token": "eyJhbGciOi...",
  "refresh_expires_in": 1800,
  "id_token": "eyJhbGciOi...",
  "id_token_expires_in": 3600,
  "token_type": "Bearer"
}

Ein Refresh Token kann nur einmal verwendet werden. Für die nächste Erneuerung ist immer das neue refresh_token aus der letzten Antwort zu verwenden. Ein bereits verwendetes Refresh Token wird mit dem Status 404 abgelehnt.

Refresh Token widerrufen

Wird ein Refresh Token nicht mehr benötigt (z. B. beim Abmelden), kann es widerrufen werden. Danach lässt es sich nicht mehr zum Erneuern verwenden.

Endpunkt:

POST /api/rest/public/security/auth/{clientName}/token/revoke

Beispiel:

curl -X POST "https://<server>/<context-path>/api/rest/public/security/auth/form/token/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "refresh_token=<refresh_token>"

Anmeldung mit Multi-Faktor-Authentifizierung (MFA)

Ist für den Benutzer MFA aktiviert, läuft die Anmeldung in zwei Schritten ab. Der Benutzer ist dabei aktiv beteiligt, da er einen MFA-Code eingeben muss.

Ablauf:

1. Anmeldung: Der Request an /security/auth/{clientName}/token (siehe Authentifizierung) liefert noch kein Access Token, sondern ein temporäres MFA-Token. Dieses verknüpft den nachfolgenden Verify-Request mit der begonnenen Anmeldung.
2. Code-Eingabe durch den Benutzer: Der Benutzer liest den aktuellen MFA-Code aus seiner Authenticator-App ab oder erhält ihn per E-Mail (siehe mfa_type) und gibt ihn ein.
3. Verifikation: Der Code wird zusammen mit dem temporären MFA-Token an den Verify-Endpunkt gesendet. Ist er korrekt, enthält die Antwort das Access Token.

Antwort der Anmeldung bei aktiver MFA:

{
  "status_type": "MFA_REQUIRED",
  "mfa_required_response": {
    "temp_token": "…",
    "message": "…",
    "expires_in": 300,
    "mfa_type": "TOTP"
  }
}

Endpunkt für die Verifikation:

POST /api/rest/public/security/auth/mfa/verify

Beispiel:

curl -X POST "https://<server>/<context-path>/api/rest/public/security/auth/mfa/verify" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "code=123456" \
  --data-urlencode "token=<temp_token>" \
  --data-urlencode "save=false"

Antwort:

{
  "success": true,
  "token": {
    "access_token": "eyJhbGciOi...",
    "expires_in": 300,
    "refresh_token": "eyJhbGciOi...",
    "refresh_expires_in": 1800,
    "id_token": "eyJhbGciOi...",
    "id_token_expires_in": 3600,
    "token_type": "Bearer"
  }
}

Das Access Token steht in token.access_token.

Falscher Code:

Ist der Code falsch, antwortet der Endpunkt trotzdem mit dem Status 200, aber mit success: false und ohne Token:

{
  "success": false
}

Es reicht nicht, nur den HTTP-Status zu prüfen. Ausschlaggebend ist das Feld success. Der Benutzer kann den Code anschließend erneut eingeben.

Neuen Code anfordern:

Ist der Code abgelaufen oder nicht angekommen, lässt sich über folgenden Endpunkt ein neues temporäres MFA-Token anfordern. Bei mfa_type EMAIL wird dabei ein neuer Code per E-Mail versendet.

POST /api/rest/public/security/auth/mfa/refresh/{temp_token}

Die Antwort enthält die Felder aus mfa_required_response direkt:

{
  "temp_token": "…",
  "message": "…",
  "expires_in": 600,
  "mfa_type": "EMAIL"
}

Für die anschließende Verifikation den neuen Code zusammen mit dem neuen temp_token verwenden.

Token in der API-Referenz verwenden

1. Die API-Referenz des Bereichs Security im Browser öffnen.
2. Den Endpunkt POST /security/auth/{clientName}/token aufklappen.
3. Auf Try it out klicken.
4. clientName (form bzw. die UUID des LDAP-Login-Dienstes), username und password eintragen.
5. Auf Execute klicken.
6. In der Antwort den Wert von token_response.access_token kopieren.
7. Die API-Referenz des gewünschten Bereichs öffnen (z. B. Form records) und oben rechts auf Authorize klicken.
8. Den kopierten Wert in das Feld für bearerAuth eintragen und mit Authorize bestätigen.

Die API-Referenz ergänzt dann bei jedem Request automatisch den Header:

Authorization: Bearer <access_token>

Danach lassen sich geschützte Endpunkte über Try it out ausführen.

Nach Ablauf des Access Tokens (siehe expires_in, z. B. 300 Sekunden) muss ein neues Token angefordert und erneut eingetragen werden.

Ungeschützte Endpunkte aufrufen

Nicht alle Endpunkte erfordern eine Authentifizierung. Öffentlich zugängliche Endpunkte, z. B. für Formulare und Benutzerportale, lassen sich ohne Access Token aufrufen.

Beispiel:

Im Beispiel wird ein Formular über die UUID des Mandanten und die UUID des Formulars abgerufen.

curl -X GET "https://<server>/<context-path>/api/rest/public/forms/{clientUuid}/{formUuid}" \
  -H "Accept: application/json"

Beispiel-Antwort (gekürzt):

{
  "uuid": "1770f6b8-6928-4c0c-8d42-6abfe09099a5",
  "name": "Testformular",
  "clientUuid": "5e7f472a-c335-470c-8a35-94a43851e79c",
  "providePath": "/form/provide/1/"
}

Häufige Fehler

401 Unauthorized

Das Access Token fehlt, ist ungültig oder abgelaufen.

• Wurde in der API-Referenz Authorize verwendet bzw. bei curl der Authorization-Header gesetzt?
• Ist das Access Token noch gültig (expires_in beachten)? Gegebenenfalls ein neues Token über den Refresh-Endpunkt anfordern.

403 Forbidden

Der Benutzer ist angemeldet, hat aber nicht die nötigen Berechtigungen. Die Berechtigungen des Benutzers in formcycle sind zu prüfen.

404 Not Found bei Anmeldung oder Token-Erneuerung

Die Security-API antwortet aus Sicherheitsgründen in mehreren Fällen einheitlich mit 404 und ohne Fehlermeldung. Mögliche Ursachen:

• falscher clientName, z. B. ldap statt der UUID des LDAP-Login-Dienstes
• falsche Zugangsdaten
• Login-Dienst nicht vorhanden oder deaktiviert
• beim Erneuern: Refresh Token bereits verwendet, widerrufen oder abgelaufen

415 Unsupported Media Type

Die Anfrage an die Security-API wurde nicht als application/x-www-form-urlencoded gesendet, z. B. als JSON. Den Content-Type-Header und das Format des Bodys prüfen.