OpenAPI REST

Mit der neuen REST‑API können Kunden und Partner ihre eigenen Anwendungen programmatisch an Evalanche anbinden. Die API basiert auf dem OpenAPI‑Standard (ehemals Swagger) und bietet damit eine standardisierte, maschinenlesbare Schnittstellenbeschreibung.

Vorteile der OpenAPI‑basierten REST‑API:

• Standardisierte Schnittstellenbeschreibung – Die API ist vollständig als OpenAPI‑Spezifikation dokumentiert. Diese kann direkt in gängige Entwicklungswerkzeuge importiert werden.
• Automatische Code‑Generierung – Aus der OpenAPI‑Spezifikation lassen sich Client‑Bibliotheken für zahlreiche Programmiersprachen automatisch erzeugen (z.B. über OpenAPI Generator).
• Interaktive Dokumentation – Die API‑Referenz bietet eine interaktive Oberfläche, in der Endpunkte direkt getestet werden können.
• Breite Tooling‑Unterstützung – OpenAPI wird von einer Vielzahl von Tools, IDEs und Plattformen unterstützt (z.B. Postman, Insomnia, Swagger UI).

In diesem Artikel erfahren Sie, wie Sie einen API‑Zugang anlegen, die erhaltenen Zugangsdaten korrekt verwenden und wie die Authentifizierung per Client Credentials Flow funktioniert.

Basisinformationen:

• OpenAPI‑Spezifikation: https://spec.openapis.org/oas/v3.1.0
• OAuth 2.0 Client Credentials: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4

Voraussetzungen

• Sie verfügen über einen Evalanche‑Account mit dem Recht „Partner Apps" zur Anlage von Applikationen und Zugängen.
• Sie haben Zugriff auf die Konfiguration Ihrer Partner‑Applikation (z.B. Backend oder Server‑Konfiguration).

API‑Zugang in Evalanche anlegen

• Navigieren Sie in der neuen Evalanche‑GUI zu Einstellungen → Applikationen und Zugänge.
• Legen Sie einen neuen Zugang vom Typ API (REST) an.
• Vergeben Sie einen Namen, damit Sie den Zugang später eindeutig zuordnen können.
• Speichern Sie den Zugang.

Nach dem Speichern erzeugt Evalanche automatisch die technischen Zugangsdaten für Ihren API‑Zugang.

Client ID und Client Secret

Nach Anlage des API‑Zugangs werden Ihnen im UI einmalig die folgenden Daten angezeigt:

• Client ID
• Client Secret

Diese Daten werden nur ein einziges Mal angezeigt. Sie müssen:

• die Client ID und das Client Secret vollständig kopieren,
• sie sicher speichern (z.B. in einem Passwort‑Manager),
• sie vertraulich behandeln und nicht öffentlich zugänglich machen (z.B. nicht im Frontend‑Code einer Browser‑App im Klartext einbinden).

Falls Sie das Client Secret verlieren oder vergessen, müssen Sie in Evalanche ein neues Secret generieren bzw. einen neuen API‑Zugang anlegen. Ein späteres erneutes Anzeigen des ursprünglichen Secrets ist aus Sicherheitsgründen nicht möglich.

Authentifizierung – Access Token anfordern

Die REST‑API verwendet den OAuth 2.0 Client Credentials Flow. Dabei authentifiziert sich Ihre Applikation direkt mit Client ID und Client Secret – ohne Benutzerinteraktion oder Redirect.

Senden Sie einen POST‑Request an den Token‑Endpunkt:

POST https://<ihre-evalanche-domain>/api/auth/v1/flow/client
Content-Type: application/x-www-form-urlencoded

Request Body (Form‑Parameter):

scope=<SCOPE>&client_id=<CLIENT-ID>&client_secret=<CLIENT-SECRET>

Parameter:

• scope – Der Zugriffsbereich, für den das Token angefordert wird.
• client_id – Die Client ID Ihres in Evalanche angelegten API‑Zugangs.
• client_secret – Das Client Secret Ihres in Evalanche angelegten API‑Zugangs.

Beispiel (cURL):

curl -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "scope=<SCOPE>&client_id=<CLIENT-ID>&client_secret=<CLIENT-SECRET>" \
  "https://<ihre-evalanche-domain>/api/auth/v1/flow/client"

Response (JSON):

{
    "access_token": "<ACCESS-TOKEN>",
    "token_type": "Bearer",
    "expires_in": <Sekunden>
}

Felder:

• access_token – Das erzeugte Access Token zur Authentifizierung an den REST‑API‑Endpunkten.
• token_type – Immer Bearer.
• expires_in – Gültigkeitsdauer des Tokens in Sekunden. Nach Ablauf muss ein neues Token angefordert werden.

Verwendung des Access Tokens

Das erhaltene Access Token muss bei jedem Aufruf der REST‑API als Bearer Token im Authorization‑Header übergeben werden:

Authorization: Bearer <ACCESS-TOKEN>

Beispiel (cURL):

curl -X GET \
  -H "Authorization: Bearer <ACCESS-TOKEN>" \
  -H "Accept: application/json" \
  "https://<ihre-evalanche-domain>/api/rest/v1/..."

Sobald das Token abgelaufen ist (expires_in), fordern Sie über den Token‑Endpunkt ein neues Access Token an.

Verfügbare REST‑API‑Endpunkte

Die vollständige Dokumentation aller verfügbaren REST‑API‑Endpunkte (Profile, Pools, Mailings etc.) finden Sie in der separaten REST‑API‑Referenz. Diese basiert auf der OpenAPI‑Spezifikation und bietet eine interaktive Übersicht aller Endpunkte, Parameter und Response‑Formate.

Die OpenAPI‑Spezifikation können Sie zudem nutzen, um:

• Client‑Code automatisch zu generieren (z.B. mit dem OpenAPI Generator),
• die API in Tools wie Postman oder Insomnia zu importieren,
• eigene Mock‑Server für die Entwicklung aufzusetzen.

Sicherheitsempfehlungen

• Speichern Sie das Client Secret niemals im Frontend oder in öffentlich zugänglichen Repositories.
• Rotieren Sie Secrets regelmäßig, insbesondere bei Verdacht auf Kompromittierung.
• Verwenden Sie HTTPS für alle Kommunikationswege (Token‑Requests, API‑Zugriffe).
• Speichern Sie Access Tokens nicht dauerhaft – fordern Sie bei Ablauf ein neues Token an.
• Geben Sie Access Tokens nicht an Dritte weiter und betten Sie sie nicht in Client‑seitigen Code ein.

Fehlerbehebung

Häufige Fehlerursachen:

• „invalid_client" oder „unauthorized_client"
  Client ID oder Client Secret sind falsch oder gehören nicht zu dem aufgerufenen API‑Zugang.
• „invalid_scope"
  Der angegebene Scope ist ungültig oder nicht für diesen API‑Zugang freigegeben.
• HTTP 401 Unauthorized
  Das Access Token fehlt, ist abgelaufen oder ungültig. Fordern Sie ein neues Token über den Token‑Endpunkt an.
• HTTP 403 Forbidden
  Der API‑Zugang hat keine Berechtigung für die angeforderte Ressource.