Authorization Code + aangepaste-omleiding-flow

Gebruik de Authorization Code + aangepaste HTTPS-omleiding-flow voor webapplicaties die namens een ingelogde gebruiker handelen en de OAuth-callback op uw eigen domein ontvangen. Deze gebruikt Authorization Code met PKCE, een exact overeenkomende HTTPS-omleidings-URI en een optioneel client secret voor vertrouwelijke server-side-clients.

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

Wat u gaat doen

Een OAuth-applicatie maken: Registreer een webapp in Prevu3D met uw HTTPS-callback-URL
Gebruikerstoegang configureren: Zorg ervoor dat de inloggende gebruiker de gegevens die het nodig heeft kan bereiken
Autoriseren met PKCE: Stuur de gebruiker door de consentpagina in de browser
De code inwisselen voor een token: Wissel de autorisatiecode in voor een access token
Uw API-URL vinden: Ontdek de basis-URL van uw organisatie (deze verschilt per regio)
Uw eerste aanroep doen: Test de verbinding met een eenvoudig verzoek

Stap 1: Uw OAuth-applicatie maken

Log in op het Prevu3D-platform.
Ga naar Instellingen → OAuth.
Klik om een nieuwe applicatie te maken.
Schakel Authorization Code-flow in.
Laat Native Application uit.
Voer uw Omleidings-URI in, bijvoorbeeld https://app.example.com/oauth/callback. Deze moet HTTPS zijn met een volledig gekwalificeerde domeinnaam en moet exact overeenkomen bij de autorisatie en het inwisselen van het token.
Schakel optioneel een client secret in als uw app deze server-side kan opslaan. Openbare browser-only-clients mogen geen secret gebruiken.
Kopieer en bewaar uw Client ID (en secret indien gegenereerd) veilig.

Stap 2: Gebruikerstoegang configureren

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

Zorg ervoor dat de gebruiker die zal inloggen inhoudstoegang heeft tot de nodes (organisaties, divisies, sites, enz.) die uw gebruiksscenario vereist.
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

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

Open 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 geregistreerde HTTPS-callback-URI (exacte overeenkomst, geen trailing slash tenzij geregistreerd)
`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 callback:

https://app.example.com/oauth/callback?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
`code_verifier`	De oorspronkelijke PKCE-verifier
`client_secret`	Alleen als uw app een secret heeft

U kunt client_id en client_secret in de body verzenden of Authorization: Basic base64(client_id:client_secret) gebruiken.

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.

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.

Probleemoplossing

Symptoom	Wat te controleren
Redirect URI mismatch bij consent of het inwisselen van het token	`redirect_uri` moet teken voor teken overeenkomen met de waarde die op de OAuth-app is geregistreerd
Invalid OAuth redirect URI bij het opslaan van de app	Gebruik `https`, een geldige domeinnaam, geen querystring of fragment in de geregistreerde URI
Bad OAuth application secret	Voeg `client_secret` alleen toe als de app met een secret is gemaakt
Grant exchange expired	Autorisatiecodes verlopen na 60 seconden; start de flow opnieuw
403 bij RCAPI-aanroepen	De gebruiker mist mogelijk inhoudstoegang, een noderol of een OAuth-scope voor de bewerking

Hebt u een loopback-omleiding nodig voor een desktopapp of CLI? Gebruik in plaats daarvan de Native Application-flow.

Wat is de volgende stap?

Native Application-flow voor localhost / PKCE zonder aangepast domein
Client Credentials-flow voor server-naar-server-toegang
Interactieve API-referentie voor de volledige endpointcatalogus