Native Application-flow

Gebruik de Native app-flow voor integraties die namens een ingelogde gebruiker vanaf diens eigen machine handelen, zoals een desktopapp, CLI of CAD-plug-in. Deze gebruikt Authorization Code met PKCE, een localhost loopback-omleiding en geen client secret. Deze gids leidt u door de installatie, van het maken van een OAuth-applicatie tot uw eerste API-aanroep.

Bekijk eerst de Aan de slag-gids als u de vereisten, netwerktoegang en het beveiligingsmodel nog niet hebt behandeld.

---

Wat u gaat doen

1. Een OAuth-applicatie maken: Registreer een native app in Prevu3D en verkrijg een Client ID
2. Gebruikerstoegang configureren: Zorg ervoor dat de inloggende gebruiker de gegevens die het nodig heeft kan bereiken
3. Autoriseren met PKCE: Stuur de gebruiker door de consentpagina in de browser
4. De code inwisselen voor een token: Wissel de autorisatiecode in voor een access token
5. Uw API-URL vinden: Ontdek de basis-URL van uw organisatie (deze verschilt per regio)
6. Uw eerste aanroep doen: Test de verbinding met een eenvoudig verzoek

Stap 1: Uw OAuth-applicatie maken

1. Log in op het Prevu3D-platform.
2. Ga naar Instellingen → OAuth.
3. Klik om een nieuwe applicatie te maken.
4. Schakel Authorization Code-flow in.
5. Schakel Native Application in. De omleidings-URI is vastgelegd op http://localhost.
6. Laat de client secret uit. Native apps gebruiken er geen.
7. Kopieer en bewaar uw Client ID veilig. U hebt deze nodig voor elke autorisatie.

Stap 2: Gebruikerstoegang configureren

De native flow roept de API aan als de ingelogde gebruiker, niet als servicegebruiker. Dit behandelt laag 2 en 3 van het beveiligingsmodel: welke nodes de gebruiker kan zien (inhoudstoegang) en wat deze ermee kan doen (rol-/rechtentoegang).

1. Zorg ervoor dat de gebruiker die zal inloggen inhoudstoegang heeft tot de nodes (organisaties, divisies, sites, enz.) die uw gebruiksscenario vereist.
2. Zorg ervoor dat de gebruiker een rol heeft op die nodes met de rechten die uw integratie nodig heeft (lezen, bewerken, beheren, enz.).

Op het consentscherm selecteert de gebruiker ook welke organisatie te autoriseren. De scopes die de gebruiker daar goedkeurt, configureren laag 1.

Stap 3: Autoriseren met PKCE

Native apps kunnen geen secret bewaren, dus de flow gebruikt PKCE om de autorisatiecode te beschermen. Genereer drie waarden voordat u de consentpagina opent:

Waarde	Hoe
code_verifier	Willekeurige string, 43 tot 128 tekens
code_challenge	BASE64URL(SHA256(code_verifier)) zonder padding
state	Willekeurige string; valideer deze wanneer de omleiding terugkomt

Start een lokale loopback-server op een vrije poort en open vervolgens de browser van de gebruiker op de consentpagina.

Consent-URL: https://cloud.prevu3d.com/oauth

Queryparameters (allemaal vereist):

Parameter	Waarde
response_type	code
code_challenge_method	S256
client_id	Uw Client ID
redirect_uri	Uw loopback-URI, bijv. http://localhost:8765 (inclusief de poort, geen trailing slash)
scopes	Eén per scope, bijv. scopes=read:basic&scopes=read:hierarchy
code_challenge	De PKCE-challenge van hierboven
state	Uw willekeurige state-waarde

Nadat de gebruiker inlogt en op Toestaan klikt, leidt de browser om naar uw loopback-URI:

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

Als de gebruiker toegang weigert, ontvangt u in plaats daarvan ?error=access_denied. Autorisatiecodes verlopen na 60 seconden, dus wissel ze meteen in.

Stap 4: De code inwisselen voor een access token

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

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

Body:

Veld	Waarde
grant_type	authorization_code
client_id	Uw Client ID
code	Code uit de omleiding
redirect_uri	Dezelfde URI die in stap 3 is gebruikt (inclusief de poort)
code_verifier	De oorspronkelijke PKCE-verifier

Verzend geen client secret voor native apps.

Voorbeeldresponse:

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

Sla beide tokens op. Gebruik de access_token voor API-aanroepen. Wanneer het verloopt, vraagt u een nieuwe aan met grant_type=refresh_token en uw opgeslagen refresh_token (geen client secret vereist).

Stap 5: Uw API-basis-URL verkrijgen

Roep het discovery-endpoint aan om de apiUrl voor uw organisatie te verkrijgen. Codeer geen regionale URL hard.

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

Headers: Authorization: Bearer <your_access_token>

Voorbeeldresponse:

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

Gebruik de apiUrl-waarde als basis voor al uw API-aanroepen. Noteer ook de organization.id, die u nodig hebt voor veel endpoints.

Stap 6: Uw eerste API-aanroep doen

U hebt nu alles wat u nodig hebt: een access token en uw basis-URL. Laten we een eenvoudig verzoek doen om de divisies van uw organisatie op te halen:

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

Voorbeeld met echte waarden:

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

Een succesvolle response met een lijst met divisies bevestigt dat uw integratie correct werkt.

Probeer het met Python

Hier is een compleet script dat alles hierboven doet. Vervang client_id door uw Client ID en voer het vervolgens uit. Het start een tijdelijke loopback-server, opent de consentpagina in uw browser en drukt de divisies van uw organisatie af zodra u goedkeurt.

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))

Probleemoplossing

Als u … ziet	Probeer dit …
Invalid OAuth grant request na het klikken op Toestaan	Bevestig dat u de Client ID van een native app gebruikt (Authorization Code en Native app ingeschakeld). Een app met alleen Client Credentials heeft geen omleidings-URI en kan deze flow niet voltooien.
Foutmelding op de consentpagina over queryparameters	Zorg ervoor dat response_type=code, code_challenge_method=S256 en alle vereiste parameters aanwezig zijn, inclusief state en scopes.
400 of 403 bij het inwisselen van het token	De code is mogelijk verlopen (limiet van 60 seconden), de redirect_uri komt mogelijk niet overeen met stap 3, of de PKCE-verifier en -challenge komen mogelijk niet overeen.
403 Forbidden bij het aanroepen van de API	Een verzoek moet alle drie de beveiligingslagen doorstaan. Controleer de OAuth-scopes, de inhoudstoegang van de ingelogde gebruiker en de rol van de gebruiker op de doelnode.
Verkeerde organisatie in API-responses	De gebruiker selecteert de organisatie op het consentscherm. Autoriseer opnieuw en kies de juiste.

Voor verbindings-, DNS- en API-URL-problemen, zie Aan de slag.

Wat is de volgende stap?

• Voeg logica toe om uw token te vernieuwen voordat het verloopt met grant_type=refresh_token en uw opgeslagen refresh token.
• Verken de API-referentie om alle beschikbare bewerkingen te zien.