Client-Credentials-Flow

Verwenden Sie den Client Credentials-Flow für Server-zu-Server-Integrationen, die im Namen Ihrer Organisation ohne angemeldeten Benutzer handeln. Dieser Leitfaden führt Sie von der Erstellung der OAuth-Anwendung bis zu Ihrem ersten API-Aufruf.

Lesen Sie zuerst den Leitfaden Erste Schritte, falls Sie Voraussetzungen, Netzwerkzugriff und das Sicherheitsmodell noch nicht abgedeckt haben.

Was Sie tun werden

Erstellen Sie eine OAuth-Anwendung — Registrieren Sie Ihre App in Prevu3D und erhalten Sie Zugangsdaten
Konfigurieren Sie den Service-Benutzerzugriff — Gewähren Sie Ihrer App Zugriff auf die benötigten Daten
Holen Sie sich ein Access Token — Authentifizieren Sie sich und erhalten Sie ein Token für die API-Nutzung
Ermitteln Sie Ihre API-URL — Finden Sie die Basis-URL Ihrer Organisation (sie variiert je nach Region)
Führen Sie Ihren ersten Aufruf durch — Testen Sie die Verbindung mit einer einfachen Anfrage

Schritt 1: Erstellen Sie Ihre OAuth-Anwendung

Melden Sie sich bei der Prevu3D Platform an.
Gehen Sie zu Settings → OAuth.
Klicken Sie, um eine neue Anwendung zu erstellen.
Wählen Sie Client Credentials als OAuth-Flow.
Weisen Sie die Berechtigungen zu, die Ihre Anwendung benötigt (dies konfiguriert Ebene 1: OAuth-Scopes). Ihr Organisationsadministrator kann Ihnen bei der Auswahl der erforderlichen Scopes helfen.
Klicken Sie auf die Schaltfläche zum Erstellen.
Kopieren und speichern Sie Ihre Client ID und Ihr Client Secret sicher. Sie benötigen diese für jeden API-Aufruf.

Schritt 2: Service-Benutzerzugriff konfigurieren

Wenn Sie eine OAuth-Anwendung erstellen, wird automatisch ein entsprechender Service-Benutzer in Ihrer Organisation angelegt. Dieser Service-Benutzer repräsentiert Ihre Anwendung bei der API-Interaktion, hat jedoch zunächst keinen Zugriff.

Dieser Schritt deckt Ebene 2 und 3 des Sicherheitsmodells ab: welche Knoten der Service-Benutzer sehen kann (Inhaltszugriff) und was er damit tun kann (Rollen- und Berechtigungszugriff).

Gehen Sie zu Settings → Users.
Suchen Sie Ihren Service-Benutzer und klicken Sie auf die Bearbeiten-Schaltfläche (er sollte ähnlich wie die erstellte OAuth-Anwendung benannt sein).
Gewähren Sie dem Service-Benutzer Inhaltszugriff auf die Knoten (Organisationen, Divisionen, Sites usw.), die Ihr Anwendungsfall erfordert.
Weisen Sie auf diesen Knoten die entsprechende Rolle / Berechtigung zu, damit der Service-Benutzer die benötigten Operationen ausführen kann (lesen, bearbeiten, verwalten usw.).
Bestätigen Sie die Änderungen.

Schritt 3: Access Token abrufen

Um die API aufzurufen, benötigen Sie zunächst ein Access Token. Senden Sie eine Anfrage an den Token-Endpunkt mit Ihrer Client ID und Ihrem Client Secret.

Endpunkt: POST https://cloud-api.prevu3d.com/oauth/token

Header:

Authorization: Basic <base64(client_id:client_secret)> — Kodieren Sie Client ID und Secret als client_id:client_secret und Base64-kodieren Sie diese Zeichenkette
Content-Type: application/x-www-form-urlencoded

Body: grant_type=client_credentials

Beispielanfrage:

POST https://cloud-api.prevu3d.com/oauth/token HTTP/1.1
Host: cloud-api.prevu3d.com
Authorization: Basic eW91ci1jbGllbnQtaWQ6eW91ci1jbGllbnQtc2VjcmV0
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Beispielantwort:

{
  "hasError": false,
  "expiresIn": 3600,
  "accessToken": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9..."
}

Speichern Sie das accessToken aus der Antwort. Das Token ist 1 Stunde gültig; danach müssen Sie auf dieselbe Weise ein neues anfordern.

Schritt 4: API-Basis-URL ermitteln

Regionale RealityConnect API (Ihre Organisation verwendet eine Region; dieser Leitfaden erklärt, wie Sie die genaue URL ermitteln):

Rufen Sie den Erkennungsendpunkt unten auf, um die apiUrl für Ihre Organisation zu erhalten. Hardcoden Sie keine regionale URL.

Endpunkt: GET https://cloud-api.prevu3d.com/oauth/api-info

Header: Authorization: Bearer <your_access_token>

Beispielantwort:

{
  "user": { "..." : "..." },
  "organization": {
    "id": "217ebd23-ec54-4af0-a6d6-4a441a6d1966",
    "name": "Test Organization"
  },
  "scopes": ["read:basic", "read:hierarchy"],
  "apiUrl": "https://api-ue1.prevu3d.com/realityconnect-api"
}

Verwenden Sie den Wert apiUrl als Basis für alle API-Aufrufe. Notieren Sie auch die organization.id — Sie benötigen sie für viele Endpunkte.

Schritt 5: Ihren ersten API-Aufruf durchführen

Sie haben jetzt alles, was Sie brauchen: ein Access Token und Ihre Basis-URL. Führen wir eine einfache Anfrage aus, um die Divisionen Ihrer Organisation abzurufen:

GET {apiUrl}/v1/nodes/{organization_id}/browse
Authorization: Bearer <your_access_token>

Beispiel mit echten Werten:

GET https://api-ue1.prevu3d.com/realityconnect-api/v1/nodes/217ebd23-ec54-4af0-a6d6-4a441a6d1966/browse HTTP/1.1
Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9...

Eine erfolgreiche Antwort mit einer Liste von Divisionen bestätigt, dass Ihre Integration korrekt funktioniert.

Mit Python ausprobieren

Hier ist ein vollständiges Skript, das alles oben Beschriebene durchführt. Ersetzen Sie client_id und client_secret durch Ihre Zugangsdaten und führen Sie es aus.

import requests
import base64
import json

client_id = "your-client-id"
client_secret = "your-client-secret"
base_url = "https://cloud-api.prevu3d.com"

# Schritt 1: Token abrufen
token_response = requests.post(
    f"{base_url}/oauth/token",
    data={"grant_type": "client_credentials"},
    headers={
        "Authorization": f'Basic {base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()}',
        "Content-Type": "application/x-www-form-urlencoded",
    },
)

token_response.raise_for_status()
access_token = token_response.json()["accessToken"]

# Schritt 2: API-URL und Organisations-ID abrufen
api_info = requests.get(
    f"{base_url}/oauth/api-info",
    headers={"Authorization": f"Bearer {access_token}"},
).json()

api_url = api_info["apiUrl"]
organization_id = api_info["organization"]["id"]

# Schritt 3: Divisionen durchsuchen
divisions = requests.get(
    f"{api_url}/v1/nodes/{organization_id}/browse",
    headers={"Authorization": f"Bearer {access_token}"},
).json()

print("Divisions:", json.dumps(divisions, indent=2))

Fehlerbehebung

Wenn Sie Folgendes sehen…	Versuchen Sie Folgendes…
401 Unauthorized beim Token-Abruf	Überprüfen Sie Client ID und Secret. Stellen Sie sicher, dass Sie `client_id:client_secret` korrekt Base64-kodieren.
403 Forbidden beim API-Aufruf	Eine Anfrage muss alle drei Sicherheitsebenen bestehen. Prüfen Sie, ob (1) Ihre OAuth-Anwendung die richtigen Scopes hat, (2) der Service-Benutzer Inhaltszugriff auf den Zielknoten hat und (3) er eine Rolle mit den erforderlichen Berechtigungen auf diesem Knoten hat.

Bei Verbindungs-, DNS- und API-URL-Problemen siehe Erste Schritte — API-URLs und Netzwerkzugriff.

Wie geht es weiter?

Fügen Sie für den Produktionseinsatz Logik hinzu, um Ihr Token vor Ablauf zu erneuern (nach 1 Stunde).
Erkunden Sie die API-Referenz, um alle verfügbaren Operationen zu sehen.