Flusso Client Credentials

Usa il flusso Client Credentials per integrazioni server-to-server che agiscono per conto della tua organizzazione senza un utente che ha effettuato l’accesso. Questa guida ti accompagna nella configurazione dalla creazione dell’applicazione OAuth alla tua prima chiamata all’API.

Rivedi prima la guida Per iniziare se non hai ancora coperto i prerequisiti, l’accesso di rete e il modello di sicurezza.

Cosa farai

Creare un’applicazione OAuth — Registra la tua app in Prevu3D e ottieni le credenziali
Configurare l’accesso dell’utente di servizio — Concedi alla tua app l’accesso ai dati di cui ha bisogno
Ottenere un access token — Autenticati e ricevi un token per usare l’API
Trovare l’URL della tua API — Scopri l’URL di base della tua organizzazione (varia in base alla regione)
Effettuare la prima chiamata — Testa la connessione con una semplice richiesta

Passaggio 1: crea la tua applicazione OAuth

Accedi alla Prevu3D Platform.
Vai su Settings → OAuth.
Fai clic per creare una nuova applicazione.
Scegli Client Credentials come flusso OAuth.
Assegna i permessi di cui la tua applicazione ha bisogno (questo configura il livello 1: scope OAuth). L’amministratore della tua organizzazione può aiutarti a decidere quali scope sono necessari.
Fai clic sul pulsante di creazione.
Copia e conserva in modo sicuro il tuo Client ID e il tuo Client Secret. Ti serviranno per ogni richiesta all’API.

Passaggio 2: configura l’accesso dell’utente di servizio

Quando crei un’applicazione OAuth, viene creato automaticamente un corrispondente utente di servizio nella tua organizzazione. Questo utente di servizio rappresenta la tua applicazione quando interagisce con l’API, ma non ha ancora alcun accesso.

Questo passaggio copre i livelli 2 e 3 del modello di sicurezza: quali nodi l’utente di servizio può vedere (accesso ai contenuti) e cosa può farci (accesso a ruoli / permessi).

Vai su Settings → Users.
Trova il tuo utente di servizio e fai clic sul pulsante di modifica (dovrebbe avere un nome simile all’applicazione OAuth che hai creato).
Concedi all’utente di servizio l’accesso ai contenuti dei nodi (organizzazioni, divisioni, siti, ecc.) richiesti dal tuo caso d’uso.
Assegna il ruolo / permesso appropriato su quei nodi affinché l’utente di servizio possa eseguire le operazioni di cui ha bisogno (lettura, modifica, gestione, ecc.).
Conferma le modifiche.

Passaggio 3: ottieni il tuo access token

Per chiamare l’API, hai prima bisogno di un access token. Invia una richiesta all’endpoint del token con il tuo Client ID e il tuo Client Secret.

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

Header:

Authorization: Basic <base64(client_id:client_secret)> — Codifica il tuo Client ID e Secret come client_id:client_secret, quindi codifica quella stringa in Base64
Content-Type: application/x-www-form-urlencoded

Body: grant_type=client_credentials

Esempio di richiesta:

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

Esempio di risposta:

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

Salva l’accessToken dalla risposta. Il token è valido per 1 ora; dopo di che dovrai richiederne uno nuovo nello stesso modo.

Passaggio 4: ottieni l’URL di base della tua API

RealityConnect API regionale (la tua organizzazione usa una regione; questa guida spiega come scoprire l’URL esatto):

Chiama l’endpoint di discovery seguente per ottenere l’apiUrl della tua organizzazione. Non codificare staticamente un URL regionale.

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

Header: Authorization: Bearer <your_access_token>

Esempio di risposta:

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

Usa il valore apiUrl come base per tutte le tue chiamate all’API. Annota anche l’organization.id — ti servirà per molti endpoint.

Passaggio 5: effettua la tua prima chiamata all’API

Ora hai tutto ciò che ti serve: un access token e il tuo URL di base. Facciamo una semplice richiesta per recuperare le divisioni della tua organizzazione:

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

Esempio con valori reali:

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

Una risposta di successo contenente un elenco di divisioni conferma che la tua integrazione funziona correttamente.

Provalo con Python

Ecco uno script completo che fa tutto quanto sopra. Sostituisci client_id e client_secret con le tue credenziali, quindi eseguilo.

import requests
import base64
import json

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

# Passaggio 1: ottieni un 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"]

# Passaggio 2: ottieni l'URL della tua API e l'ID dell'organizzazione
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"]

# Passaggio 3: esplora le divisioni
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))

Risoluzione dei problemi

Se vedi…	Prova questo…
401 Unauthorized durante l’ottenimento di un token	Ricontrolla il tuo Client ID e Secret. Assicurati di codificare correttamente in Base64 `client_id:client_secret`.
403 Forbidden durante la chiamata all’API	Una richiesta deve superare tutti e tre i livelli di sicurezza. Verifica che (1) la tua applicazione OAuth abbia gli scope corretti, (2) l’utente di servizio abbia l’accesso ai contenuti del nodo di destinazione e (3) abbia un ruolo con i permessi richiesti su quel nodo.

Per problemi di connessione, DNS e URL dell’API, consulta Per iniziare — URL dell’API e accesso di rete.

Cosa c’è dopo?

Aggiungi la logica per aggiornare il tuo token prima che scada (dopo 1 ora).
Esplora il riferimento API per vedere tutte le operazioni disponibili.