Flujo de Client Credentials

Usa el flujo Client Credentials para integraciones de servidor a servidor que actúan en nombre de tu organización sin un usuario con sesión iniciada. Esta guía te acompaña en la configuración, desde la creación de la aplicación OAuth hasta tu primera llamada a la API.

Revisa primero la guía de Primeros pasos si aún no has cubierto los requisitos previos, el acceso de red y el modelo de seguridad.

Lo que harás

Crear una aplicación OAuth — Registra tu app en Prevu3D y obtén las credenciales
Configurar el acceso del usuario de servicio — Da a tu app acceso a los datos que necesita
Obtener un token de acceso — Autentícate y recibe un token para usar la API
Encontrar tu URL de la API — Descubre la URL base de tu organización (varía según la región)
Realizar tu primera llamada — Prueba la conexión con una solicitud sencilla

Paso 1: crea tu aplicación OAuth

Inicia sesión en la Plataforma Prevu3D.
Ve a Settings → OAuth.
Haz clic para crear una nueva aplicación.
Elige Client Credentials como flujo OAuth.
Asigna los permisos que necesita tu aplicación (esto configura la capa 1: ámbitos de OAuth). El administrador de tu organización puede ayudarte a decidir qué ámbitos son necesarios.
Haz clic en el botón de crear.
Copia y guarda de forma segura tu Client ID y tu Client Secret. Los necesitarás para cada solicitud a la API.

Paso 2: configura el acceso del usuario de servicio

Cuando creas una aplicación OAuth, se crea automáticamente un usuario de servicio correspondiente en tu organización. Este usuario de servicio representa a tu aplicación cuando interactúa con la API, pero todavía no tiene ningún acceso.

Este paso cubre las capas 2 y 3 del modelo de seguridad: qué nodos puede ver el usuario de servicio (acceso al contenido) y qué puede hacer con ellos (acceso por rol / permiso).

Ve a Settings → Users.
Busca tu usuario de servicio y haz clic en el botón de editar (debería tener un nombre similar al de la aplicación OAuth que creaste).
Concede al usuario de servicio acceso al contenido de los nodos (organizaciones, divisiones, sitios, etc.) que requiere tu caso de uso.
Asigna el rol / permiso apropiado en esos nodos para que el usuario de servicio pueda realizar las operaciones que necesita (leer, editar, gestionar, etc.).
Confirma los cambios.

Paso 3: obtén tu token de acceso

Para llamar a la API, primero necesitas un token de acceso. Envía una solicitud al endpoint de token con tu Client ID y tu Client Secret.

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

Cabeceras:

Authorization: Basic <base64(client_id:client_secret)> — Codifica tu Client ID y tu secreto como client_id:client_secret y luego codifica esa cadena en Base64
Content-Type: application/x-www-form-urlencoded

Cuerpo: grant_type=client_credentials

Ejemplo de solicitud:

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

Ejemplo de respuesta:

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

Guarda el accessToken de la respuesta. El token es válido durante 1 hora; después de eso, tendrás que solicitar uno nuevo de la misma forma.

Paso 4: obtén la URL base de tu API

API regional de RealityConnect (tu organización usa una única región; esta guía explica cómo descubrir la URL exacta):

Llama al endpoint de detección de abajo para obtener la apiUrl de tu organización. No codifiques de forma fija una URL regional.

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

Cabeceras: Authorization: Bearer <your_access_token>

Ejemplo de respuesta:

{
  "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 el valor de apiUrl como base para todas tus llamadas a la API. Anota también el organization.id — lo necesitarás para muchos endpoints.

Paso 5: realiza tu primera llamada a la API

Ahora tienes todo lo necesario: un token de acceso y tu URL base. Hagamos una solicitud sencilla para recuperar las divisiones de tu organización:

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

Ejemplo con valores reales:

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

Una respuesta correcta que contenga una lista de divisiones confirma que tu integración funciona correctamente.

Pruébalo con Python

Aquí tienes un script completo que hace todo lo anterior. Reemplaza client_id y client_secret por tus credenciales y luego ejecútalo.

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

Resolución de problemas

Si ves…	Prueba esto…
401 Unauthorized al obtener un token	Vuelve a comprobar tu Client ID y tu secreto. Asegúrate de codificar `client_id:client_secret` en Base64 correctamente.
403 Forbidden al llamar a la API	Una solicitud debe superar las tres capas de seguridad. Comprueba que (1) tu aplicación OAuth tenga los ámbitos correctos, (2) el usuario de servicio tenga acceso al contenido del nodo de destino y (3) tenga un rol con los permisos necesarios en ese nodo.

Para problemas de conexión, DNS y URL de la API, consulta Primeros pasos — URLs de la API y acceso de red.

¿Qué sigue?

Añade lógica para renovar tu token antes de que caduque (después de 1 hora).
Explora la referencia de la API para ver todas las operaciones disponibles.