Zum Hauptinhalt springen
Version: 4.1 (2026 H2)

Authentifizierung

Die primedocs Web API verwendet OAuth 2.0 mit Bearer Tokens zur Authentifizierung. Clients müssen in der primedocs.config registriert sein, bevor sie Access Tokens anfordern können.

Übersicht​

Die Authentifizierung erfolgt über den im primedocs enthaltenen Identity Server (IdS). Nach der Registrierung eines Clients kann dieser ein Access Token über den client_credentials Grant Type anfordern.

Das Access Token muss dann im Authorization-Header aller API-Aufrufe mitgegeben werden:

Authorization: Bearer <access_token>

Client-Registrierung​

Um einen Client zu registrieren, muss ein Eintrag in der primedocs.config vorgenommen werden. Siehe primedocs.config für Details.

Token-Anfrage​

Access Tokens werden vom Token-Endpunkt angefordert:

POST https://{instanz}/ids/connect/token

Der Request-Body muss folgendes enthalten:

  • client_id — die registrierte Client-ID
  • client_secret — das Client-Secret
  • grant_type — muss client_credentials sein
  • scope — der benötigte Scope (z.B. pd_AdminWebApi oder pd_ConnectWebApi)

API-Scopes​

ScopeBeschreibung
pd_AdminWebApiZugriff auf die Admin API für administrative Operationen
pd_ConnectWebApiZugriff auf die Connect API und Connect Session API für die Dokumentgenerierung

Ende-zu-Ende-Beispiel​

1. Access Token anfordern (client_credentials-Grant am Token-Endpunkt):

POST https://{instanz}/ids/connect/token
Content-Type: application/x-www-form-urlencoded

client_id=CustomApiClient&client_secret=CustomClient_Secret_123&grant_type=client_credentials&scope=pd_ConnectWebApi

2. Beispiel-Antwort des Token-Endpunkts:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "pd_ConnectWebApi"
}

3. Access Token verwenden — das access_token wird bei jedem API-Aufruf im Authorization-Header mitgegeben:

GET https://{instanz}/webapi/api/v3/{datasourceId}/Admin/Users?page=1&pageSize=10
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...
hinweis

Läuft ein Token ab (401 Unauthorized), wird über Schritt 1 einfach ein neues angefordert. Die Gültigkeitsdauer richtet sich nach der Konfiguration des Identity Servers.

Beispiele​

Vollständige PowerShell-Beispiele zur Anforderung und Verwendung von Access Tokens finden Sie auf den einzelnen API-Seiten: