Client Credentials-flow

Gebruik de Client Credentials-flow voor server-naar-server-integraties die namens uw organisatie handelen zonder ingelogde gebruiker. 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 uw app in Prevu3D en verkrijg inloggegevens
2. Servicegebruikertoegang configureren — Geef uw app toegang tot de gegevens die het nodig heeft
3. Een access token verkrijgen — Verifieer en ontvang een token om de API te gebruiken
4. Uw API-URL vinden — Ontdek de basis-URL van uw organisatie (deze verschilt per regio)
5. 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. Kies Client Credentials als de OAuth-flow.
5. Wijs de rechten toe die uw applicatie nodig heeft (dit configureert laag 1: OAuth-scopes). Uw organisatiebeheerder kan u helpen beslissen welke scopes vereist zijn.
6. Klik op de knop Maken.
7. Kopieer en bewaar uw Client ID en Client Secret veilig. U hebt deze nodig voor elk API-verzoek.

Opgepast

Bewaar deze inloggegevens veilig (bijv. omgevingsvariabelen of een secrets manager). Commit ze nooit naar broncodebeheer en stel ze nooit bloot in client-side-applicaties.

Stap 2: Servicegebruikertoegang configureren

Wanneer u een OAuth-applicatie maakt, wordt er automatisch een bijbehorende servicegebruiker in uw organisatie gemaakt. Deze servicegebruiker vertegenwoordigt uw applicatie wanneer deze met de API interacteert, maar heeft nog geen toegang.

Deze stap behandelt laag 2 en 3 van het beveiligingsmodel: welke nodes de servicegebruiker kan zien (inhoudstoegang) en wat deze ermee kan doen (rol-/rechtentoegang).

1. Ga naar Instellingen → Gebruikers.
2. Zoek uw servicegebruiker en klik op de knop Bewerken (deze zou een vergelijkbare naam moeten hebben als de OAuth-applicatie die u hebt gemaakt).
3. Verleen de servicegebruiker inhoudstoegang tot de nodes (organisaties, divisies, sites, enz.) die uw gebruiksscenario vereist.
4. Wijs de juiste rol / het juiste recht toe op die nodes, zodat de servicegebruiker de bewerkingen kan uitvoeren die het nodig heeft (lezen, bewerken, beheren, enz.).
5. Bevestig de wijzigingen.

Stap 3: Uw access token verkrijgen

Om de API aan te roepen, hebt u eerst een access token nodig. Verzend een verzoek naar het token-endpoint met uw Client ID en Client Secret.

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

Headers:

• Authorization: Basic <base64(client_id:client_secret)> — Codeer uw Client ID en Secret als client_id:client_secret en codeer die string vervolgens met Base64
• Content-Type: application/x-www-form-urlencoded

Body: grant_type=client_credentials

Voorbeeldverzoek:

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

Voorbeeldresponse:

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

Sla de accessToken uit de response op. Het token is 1 uur geldig; daarna moet u op dezelfde manier een nieuwe aanvragen.

Stap 4: Uw API-basis-URL verkrijgen

Regionale RealityConnect API (uw organisatie gebruikt één regio; deze gids legt uit hoe u de exacte URL vindt):

• https://api-ue1.prevu3d.com/realityconnect-api/
• https://api-ec1.prevu3d.com/realityconnect-api/
• https://api-an1.prevu3d.com/realityconnect-api/
• https://api-cc1.prevu3d.com/realityconnect-api/

Roep het onderstaande 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 — u hebt deze nodig voor veel endpoints.

Stap 5: 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 en client_secret door uw inloggegevens en voer het vervolgens uit.

import requests
import base64
import json

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

# Step 1: Get a token
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"]

# 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 …
401 Unauthorized bij het verkrijgen van een token	Controleer uw Client ID en Secret nogmaals. Zorg ervoor dat u client_id:client_secret correct met Base64 codeert.
403 Forbidden bij het aanroepen van de API	Een verzoek moet alle drie de beveiligingslagen doorstaan. Controleer of (1) uw OAuth-applicatie de juiste scopes heeft, (2) de servicegebruiker inhoudstoegang heeft tot de doelnode en (3) deze een rol heeft met de vereiste rechten op die node.

Voor verbindings-, DNS- en API-URL-problemen, zie Aan de slag — API-URL’s en netwerktoegang.

Wat is de volgende stap?

• Voeg logica toe om uw token te vernieuwen voordat het verloopt (na 1 uur).
• Verken de API-referentie om alle beschikbare bewerkingen te zien.