Flux Client Credentials

Utilisez le flux Client Credentials pour les intégrations serveur à serveur qui agissent au nom de votre organisation sans utilisateur connecté. Ce guide vous accompagne de la création de l’application OAuth jusqu’à votre premier appel API.

Consultez d’abord le guide Premiers pas si vous n’avez pas encore couvert les prérequis, l’accès réseau et le modèle de sécurité.

Ce que vous allez faire

Créer une application OAuth — Enregistrer votre application dans Prevu3D et obtenir vos identifiants
Configurer l’accès de l’utilisateur de service — Donner à votre application l’accès aux données dont elle a besoin
Obtenir un jeton d’accès — S’authentifier et recevoir un jeton pour utiliser l’API
Trouver votre URL d’API — Découvrir l’URL de base de votre organisation (elle varie selon la région)
Effectuer votre premier appel — Tester la connexion avec une requête simple

Étape 1 : Créer votre application OAuth

Connectez-vous à la Prevu3D Platform.
Allez dans Settings → OAuth.
Cliquez pour créer une nouvelle application.
Choisissez Client Credentials comme flux OAuth.
Attribuez les permissions dont votre application a besoin (cela configure la couche 1 : scopes OAuth). Votre administrateur d’organisation peut vous aider à déterminer les scopes requis.
Cliquez sur le bouton de création.
Copiez et stockez en toute sécurité votre Client ID et votre Client Secret. Vous en aurez besoin pour chaque requête API.

Étape 2 : Configurer l’accès de l’utilisateur de service

Lorsque vous créez une application OAuth, un utilisateur de service correspondant est automatiquement créé dans votre organisation. Cet utilisateur de service représente votre application lorsqu’elle interagit avec l’API, mais il n’a pas encore d’accès.

Cette étape couvre les couches 2 et 3 du modèle de sécurité : quels nœuds l’utilisateur de service peut voir (accès au contenu) et ce qu’il peut en faire (accès par rôle / permission).

Allez dans Settings → Users.
Trouvez votre utilisateur de service et cliquez sur le bouton de modification (il devrait porter un nom similaire à l’application OAuth que vous avez créée).
Accordez à l’utilisateur de service un accès au contenu aux nœuds (organisations, divisions, sites, etc.) requis par votre cas d’utilisation.
Attribuez le rôle / permission approprié sur ces nœuds pour que l’utilisateur de service puisse effectuer les opérations nécessaires (lire, modifier, gérer, etc.).
Confirmez les modifications.

Étape 3 : Obtenir votre jeton d’accès

Pour appeler l’API, vous avez d’abord besoin d’un jeton d’accès. Envoyez une requête au point de terminaison de jeton avec votre Client ID et Client Secret.

Point de terminaison : POST https://cloud-api.prevu3d.com/oauth/token

En-têtes :

Authorization: Basic <base64(client_id:client_secret)> — Encodez votre Client ID et Secret sous la forme client_id:client_secret, puis encodez cette chaîne en Base64
Content-Type: application/x-www-form-urlencoded

Corps : grant_type=client_credentials

Exemple de requête :

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

Exemple de réponse :

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

Enregistrez le accessToken de la réponse. Le jeton est valide pendant 1 heure ; après cela, vous devrez en demander un nouveau de la même manière.

Étape 4 : Obtenir votre URL de base d’API

RealityConnect API régionale (votre organisation utilise une région ; ce guide explique comment découvrir l’URL exacte) :

Appelez le point de terminaison de découverte ci-dessous pour obtenir l’apiUrl de votre organisation. Ne codez pas une URL régionale en dur.

Point de terminaison : GET https://cloud-api.prevu3d.com/oauth/api-info

En-têtes : Authorization: Bearer <your_access_token>

Exemple de réponse :

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

Utilisez la valeur apiUrl comme base pour tous vos appels API. Notez également l’organization.id — vous en aurez besoin pour de nombreux points de terminaison.

Étape 5 : Effectuer votre premier appel API

Vous avez maintenant tout ce qu’il vous faut : un jeton d’accès et votre URL de base. Effectuons une requête simple pour récupérer les divisions de votre organisation :

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

Exemple avec des valeurs réelles :

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

Une réponse réussie contenant une liste de divisions confirme que votre intégration fonctionne correctement.

Essayez avec Python

Voici un script complet qui effectue tout ce qui précède. Remplacez client_id et client_secret par vos identifiants, puis exécutez-le.

import requests
import base64
import json

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

# Étape 1 : Obtenir un jeton
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"]

# Étape 2 : Obtenir l'URL d'API et l'ID d'organisation
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"]

# Étape 3 : Parcourir les 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))

Dépannage

Si vous voyez…	Essayez ceci…
401 Unauthorized lors de l’obtention du jeton	Vérifiez votre Client ID et Secret. Assurez-vous d’encoder correctement `client_id:client_secret` en Base64.
403 Forbidden lors de l’appel API	Une requête doit passer les trois couches de sécurité. Vérifiez que (1) votre application OAuth a les bons scopes, (2) l’utilisateur de service a un accès au contenu du nœud cible, et (3) il a un rôle avec les permissions requises sur ce nœud.

Pour les problèmes de connexion, DNS et URL d’API, consultez Premiers pas — URL de l’API et accès réseau.

Et ensuite ?

Pour un usage en production, ajoutez une logique pour renouveler votre jeton avant son expiration (après 1 heure).
Explorez la référence API pour voir toutes les opérations disponibles.