Native-Anwendungsflow

Verwenden Sie den Native app-Flow für Integrationen, die im Namen eines angemeldeten Benutzers von dessen eigenem Rechner aus handeln, z. B. Desktop-Apps, CLI-Tools oder CAD-Plugins. Er nutzt Authorization Code mit PKCE, einen localhost-Loopback-Redirect und kein Client Secret. 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

1. Erstellen Sie eine OAuth-Anwendung: Registrieren Sie eine native App in Prevu3D und erhalten Sie eine Client ID
2. Konfigurieren Sie den Benutzerzugriff: Stellen Sie sicher, dass der sich anmeldende Benutzer auf die benötigten Daten zugreifen kann
3. Autorisieren mit PKCE: Leiten Sie den Benutzer über die Browser-Zustimmungsseite
4. Tauschen Sie den Code gegen ein Token: Tauschen Sie den Authorization Code gegen ein Access Token
5. Ermitteln Sie Ihre API-URL: Finden Sie die Basis-URL Ihrer Organisation (sie variiert je nach Region)
6. Führen Sie Ihren ersten Aufruf durch: Testen Sie die Verbindung mit einer einfachen Anfrage

Schritt 1: Erstellen Sie Ihre OAuth-Anwendung

1. Melden Sie sich bei der Prevu3D Platform an (oder in Ihrer Preproduction-Umgebung).
2. Gehen Sie zu Settings → OAuth.
3. Klicken Sie, um eine neue Anwendung zu erstellen.
4. Aktivieren Sie Authorization Code flow.
5. Aktivieren Sie Native Application. Die Redirect-URI ist fest auf http://localhost gesetzt.
6. Lassen Sie das Client Secret ausgeschaltet. Native Apps verwenden keins.
7. Kopieren und speichern Sie Ihre Client ID sicher. Sie benötigen sie für jede Autorisierung.

Hinweis

OAuth-Anwendungen sind umgebungsspezifisch. Erstellen und verwenden Sie Zugangsdaten in derselben Umgebung (Produktion, Preproduction oder lokal), die Ihre Integration ansteuert.

Schritt 2: Benutzerzugriff konfigurieren

Der native Flow ruft die API als angemeldeter Benutzer auf, nicht als Service-Benutzer. Dies betrifft Ebene 2 und 3 des Sicherheitsmodells: welche Knoten der Benutzer sehen kann (Inhaltszugriff) und was er damit tun kann (Rollen- und Berechtigungszugriff).

1. Stellen Sie sicher, dass der Benutzer, der sich anmeldet, Inhaltszugriff auf die Knoten (Organisationen, Divisionen, Sites usw.) hat, die Ihr Anwendungsfall erfordert.
2. Stellen Sie sicher, dass der Benutzer auf diesen Knoten eine Rolle mit den Berechtigungen hat, die Ihre Integration benötigt (lesen, bearbeiten, verwalten usw.).

Auf dem Zustimmungsbildschirm wählt der Benutzer außerdem, welche Organisation autorisiert werden soll. Die dort genehmigten Scopes konfigurieren Ebene 1.

Schritt 3: Mit PKCE autorisieren

Native Apps können kein Secret speichern, daher schützt der Flow den Authorization Code mit PKCE. Generieren Sie vor dem Öffnen der Zustimmungsseite drei Werte:

Wert	Vorgehen
code_verifier	Zufällige Zeichenkette, 43 bis 128 Zeichen
code_challenge	BASE64URL(SHA256(code_verifier)) ohne Padding
state	Zufällige Zeichenkette; beim Zurückleiten validieren

Starten Sie einen lokalen Loopback-Server auf einem freien Port und öffnen Sie dann den Browser des Benutzers auf der Zustimmungsseite.

Produktions-Zustimmungs-URL: https://cloud.prevu3d.com/oauth

Preproduction-Zustimmungs-URL: https://cloud.preproduction.prevu3d-int.com/oauth

Query-Parameter (alle erforderlich):

Parameter	Wert
response_type	code
code_challenge_method	S256
client_id	Ihre Client ID
redirect_uri	Ihre Loopback-URI, z. B. http://localhost:8765 (Port angeben, kein abschließender Schrägstrich)
scopes	Ein Parameter pro Scope, z. B. scopes=read:basic&scopes=read:hierarchy
code_challenge	Der PKCE-Challenge-Wert von oben
state	Ihr zufälliger State-Wert

Nachdem sich der Benutzer angemeldet und auf Allow geklickt hat, leitet der Browser zu Ihrer Loopback-URI weiter:

http://localhost:8765/?code={authorization_code}&state={state}

Lehnt der Benutzer den Zugriff ab, erhalten Sie stattdessen ?error=access_denied. Authorization Codes laufen nach 60 Sekunden ab. Tauschen Sie sie daher sofort aus.

Schritt 4: Code gegen ein Access Token tauschen

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

Header: Content-Type: application/x-www-form-urlencoded

Body:

Feld	Wert
grant_type	authorization_code
client_id	Ihre Client ID
code	Code aus dem Redirect
redirect_uri	Dieselbe URI wie in Schritt 3 (einschließlich Port)
code_verifier	Der ursprüngliche PKCE-Verifier

Senden Sie für native Apps kein Client Secret.

Beispielantwort:

{
  "hasError": false,
  "expires_in": 86400,
  "access_token": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "..."
}

Speichern Sie beide Tokens. Verwenden Sie das access_token für API-Aufrufe. Wenn es abläuft, fordern Sie ein neues mit grant_type=refresh_token und Ihrem gespeicherten refresh_token an (kein Client Secret erforderlich).

Schritt 5: API-Basis-URL ermitteln

Rufen Sie den Erkennungsendpunkt 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, die Sie für viele Endpunkte benötigen.

Schritt 6: Ihren ersten API-Aufruf durchführen

Sie haben jetzt alles, was Sie brauchen: ein Access Token und Ihre Basis-URL. Stellen Sie eine einfache Anfrage, 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 ausführt. Ersetzen Sie client_id durch Ihre Client ID und führen Sie es aus. Es startet einen temporären Loopback-Server, öffnet die Zustimmungsseite in Ihrem Browser und gibt die Divisionen Ihrer Organisation aus, sobald Sie zustimmen.

import base64
import hashlib
import json
import secrets
import webbrowser
from http.server import BaseHTTPRequestHandler, HTTPServer
from urllib.parse import parse_qs, quote, urlencode, urlparse

import requests

client_id = "your-client-id"
base_url = "https://cloud-api.prevu3d.com"
scopes = ["read:basic", "read:hierarchy"]

# Step 1: Authorize with PKCE and get an access token
verifier = secrets.token_urlsafe(48)[:64]
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).decode().rstrip("=")
state = secrets.token_urlsafe(32)
auth_result = {"code": None, "state": None}


class Handler(BaseHTTPRequestHandler):
    def log_message(self, *args):
        pass

    def do_GET(self):
        query = parse_qs(urlparse(self.path).query)
        auth_result["code"] = query.get("code", [None])[0]
        auth_result["state"] = query.get("state", [None])[0]
        self.send_response(200)
        self.end_headers()


server = HTTPServer(("localhost", 0), Handler)
redirect_uri = f"http://localhost:{server.server_address[1]}"
consent_params = urlencode(
    {
        "response_type": "code",
        "code_challenge_method": "S256",
        "client_id": client_id,
        "redirect_uri": redirect_uri,
        "code_challenge": challenge,
        "state": state,
    }
)
consent_url = f"{base_url.replace('cloud-api.', 'cloud.', 1)}/oauth?{consent_params}"
consent_url += "&" + "&".join(f"scopes={quote(scope)}" for scope in scopes)

webbrowser.open(consent_url)
server.handle_request()

if auth_result["state"] != state:
    raise RuntimeError("Invalid state")
if not auth_result["code"]:
    raise RuntimeError("Authorization failed")

token_response = requests.post(
    f"{base_url}/oauth/token",
    data={
        "grant_type": "authorization_code",
        "client_id": client_id,
        "code": auth_result["code"],
        "redirect_uri": redirect_uri,
        "code_verifier": verifier,
    },
)
token_response.raise_for_status()
access_token = token_response.json()["access_token"]

# Step 2: Get your API URL and org ID
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"]

# Step 3: Browse divisions
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…
Invalid OAuth grant request nach Klick auf Allow	Prüfen Sie, ob Sie die Client ID einer nativen App verwenden (Authorization Code und Native app aktiviert). Eine reine Client-Credentials-App hat keine Redirect-URI und kann diesen Flow nicht abschließen.
Redirect URI domain must be verified beim Erstellen der App	Geben Sie keine benutzerdefinierte Redirect-URI ein. Aktivieren Sie stattdessen den Schalter Native app. Derzeit kann nur http://localhost (ohne Port, ohne Secret) registriert werden.
Fehler auf der Zustimmungsseite zu Query-Parametern	Stellen Sie sicher, dass response_type=code, code_challenge_method=S256 und alle erforderlichen Parameter vorhanden sind, einschließlich state und scopes.
400 oder 403 beim Token-Austausch	Der Code ist möglicherweise abgelaufen (60-Sekunden-Limit), die redirect_uri stimmt möglicherweise nicht mit Schritt 3 überein, oder PKCE-Verifier und Challenge passen nicht zusammen.
403 Forbidden beim API-Aufruf	Eine Anfrage muss alle drei Sicherheitsebenen bestehen. Prüfen Sie die OAuth-Scopes, den Inhaltszugriff des angemeldeten Benutzers und die Rolle des Benutzers auf dem Zielknoten.
Falsche Organisation in API-Antworten	Der Benutzer wählt die Organisation auf dem Zustimmungsbildschirm. Autorisieren Sie erneut und wählen Sie die richtige Organisation.

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

Wie geht es weiter?

• Für den Produktionseinsatz fügen Sie Logik hinzu, um Ihr Token vor Ablauf mit grant_type=refresh_token und Ihrem gespeicherten Refresh Token zu erneuern.
• Erkunden Sie die API-Referenz, um alle verfügbaren Operationen zu sehen.