Postman Guide

Diese Anleitung beschreibt den OAuth 2.0 Authorization-Code-Flow mit der Postman-Collection „DocCheck Access – OAuth2“, um ein Access Token zu erhalten und geschützte Userdaten abzurufen.

Postman Collection herunterladen

Zweck

• Authorization Code holen → gegen Access Token tauschen → Userdaten-Endpunkt abrufen.

Voraussetzungen

• DocCheck Client-Credentials (client_id, client_secret)
• Registrierte redirect_uri (muss exakt mit der bei DocCheck hinterlegten URL übereinstimmen)
• Postman installiert

Lizenzunterschiede

Basic

• Access Token kann abgeholt werden (Authorization Code → Token Exchange).
• Keine Parameterübergabe via state oder scopes möglich.
• Wichtig: scope und state müssen in allen Requests deaktiviert (nicht gesendet) werden, nicht nur leer gelassen.
• Zugriff auf den Userdaten-Endpunkt ist nicht Bestandteil der Basic-Lizenz.

Economy & Business

• Der Parameter state kann übergeben und geprüft werden.
• scopes können gesetzt/abgefragt werden.
• Das Access Token kann zusätzlich verwendet werden, um Userdaten am Endpunkt user_data_url abzurufen.

Vorbereitung: Collection-Variablen setzen

Öffnen Sie in Postman die Collection und tragen Sie unter „Variables“ Folgendes ein:

• client_id: Ihre Client-ID
• client_secret: Ihr Client-Secret
• redirect_uri: Ihre registrierte Redirect-URL
• scopes: gewünschte Scopes (nur Economy/Business; bei Basic nicht verwenden und in Requests deaktivieren)
• state: zufälliger String zur CSRF-Absicherung (nur Economy/Business; bei Basic nicht verwenden und in Requests deaktivieren)
• auth_code: bleibt leer; wird nach Schritt 1 gesetzt
• auth_url: https://auth.doccheck.com/en/authorize?
• token_url: https://auth.doccheck.com/token
• user_data_url: https://auth.doccheck.com/api/users/data

Basic-Lizenz

Auch wenn scopes/state als Collection-Variablen leer sind, sendet Postman gegebenenfalls leere Query-Parameter. Deaktivieren Sie die Parameter im jeweiligen Request (im Tab „Params“ Checkbox abwählen oder Parameterzeile entfernen), damit sie nicht übertragen werden.

Ablauf

1. Authorization Code anfordern (Request „Auth“)

• Öffnen Sie den Request „Auth“.
• Prüfen Sie die Query-Parameter. Sie verwenden die gesetzten Variablen.
• Basic: Deaktivieren/entfernen Sie die Parameter scope und state im Tab „Params“, sodass sie nicht in der URL enthalten sind.
• Öffnen Sie die vollständige URL im Browser (in Postman über „Open in browser“ oder URL kopieren).
• Melden Sie sich bei DocCheck an und erteilen Sie die Zustimmung.
• Nach dem Redirect zur redirect_uri kopieren Sie den Parameter code aus der Ziel-URL. Bei Economy/Business zusätzlich state prüfen.
• Tragen Sie den Wert in die Collection-Variable auth_code ein.

2. Access Token holen (Request „Token“)

• Öffnen Sie „Token“ (POST https://auth.doccheck.com/token).
• Body: x-www-form-urlencoded mit:
  • client_id =
  • client_secret =
  • grant_type = authorization_code
  • code =
  • redirect_uri =
• Senden Sie den Request. Die erwartete Antwort enthält unter anderem access_token, token_type, expires_in und gegebenenfalls refresh_token.

Optional: Token automatisch als Collection-Variable speichern im Tab „Tests“ des Requests „Token“:

pm.collectionVariables.set('access_token', pm.response.json().access_token);

3. Geschützte Ressource abrufen (Request „Userdata“)

Lizenzanforderung

Dieser Schritt ist nur für Economy/Business verfügbar. In der Basic-Lizenz ist der Zugriff auf den Userdaten-Endpunkt nicht vorgesehen.

• Öffnen Sie „Userdata“ (GET https://auth.doccheck.com/api/users/data).
• Authentifizierung setzen:
  • Einfach: Tab „Authorization“ → Typ „Bearer Token“ → access_token einfügen (manuell aus Schritt 2 oder , falls per Test gespeichert).
  • Alternativ im Header: Authorization: Bearer <access_token>.
• Senden Sie den Request. Erwartete Antwort: 200 OK mit Userdaten, abhängig von Scopes und Freigaben.

Scopes

• Gilt für Economy/Business. Bei Basic stehen scopes nicht zur Verfügung und müssen deaktiviert werden (Parameter nicht mitsenden).
• Scopes je nach Lizenzmodell wählen. Leere scopes fragen im Login-Prozess keine Scopes ab und stehen dementsprechend nicht am Userdaten-Endpunkt bereit. Exakte Scope-Namen entnehmen Sie der DocCheck-Dokumentation.

Optional: Integrierten OAuth 2.0-Flow in Postman nutzen

Im Tab „Authorization“ eines Requests Typ „OAuth 2.0“ wählen → „Get New Access Token“:

• Auth URL:
• Access Token URL:
• Client ID:
• Client Secret:
• Scope:
• State:
• Redirect URI: Ihre registrierte redirect_uri
• „Authorize using browser“ aktivieren → Login → „Use Token“.

Hinweis:

• Economy/Business: Scope/State wie benötigt befüllen.
• Basic: Scope und State komplett leer lassen und sicherstellen, dass sie in der generierten Autorisierungs-URL nicht vorkommen (kein &scope=/&state=). Gegebenenfalls im Request-Auth-Helper vor dem Autorisieren prüfen/entfernen.