Flujo de Authorization Code + redireccionamiento personalizado

Usa el flujo Authorization Code + redireccionamiento HTTPS personalizado para aplicaciones web que actúan en nombre de un usuario con sesión iniciada y reciben la devolución de llamada de OAuth en tu propio dominio. Usa Authorization Code con PKCE, un URI de redireccionamiento HTTPS de coincidencia exacta y un secreto de cliente opcional para clientes confidenciales del lado del servidor.

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

1. Crear una aplicación OAuth: registra una app web en Prevu3D con tu URL de devolución de llamada HTTPS
2. Configurar el acceso del usuario: asegúrate de que el usuario que inicia sesión pueda acceder a los datos que necesita
3. Autorizar con PKCE: envía al usuario a través de la página de consentimiento del navegador
4. Intercambiar el código por un token: canjea el código de autorización por un token de acceso
5. Encontrar tu URL de la API: descubre la URL base de tu organización (varía según la región)
6. Realizar tu primera llamada: prueba la conexión con una solicitud sencilla

Paso 1: crea tu aplicación OAuth

1. Inicia sesión en la Plataforma Prevu3D.
2. Ve a Settings → OAuth.
3. Haz clic para crear una nueva aplicación.
4. Activa Authorization Code flow.
5. Deja Native Application desactivado.
6. Introduce tu Redirect URI, por ejemplo https://app.example.com/oauth/callback. Debe ser HTTPS con un nombre de dominio totalmente cualificado y debe coincidir exactamente en el momento de la autorización y del intercambio de token.
7. Opcionalmente, activa un secreto de cliente si tu app puede almacenarlo en el servidor. Los clientes públicos solo de navegador no deben usar un secreto.
8. Copia y guarda de forma segura tu Client ID (y el secreto, si se genera).

Paso 2: configura el acceso del usuario

Este flujo llama a la API como el usuario con sesión iniciada, no como un usuario de servicio. Esto cubre las capas 2 y 3 del modelo de seguridad: qué nodos puede ver el usuario (acceso al contenido) y qué puede hacer con ellos (acceso por rol / permiso).

1. Asegúrate de que el usuario que iniciará sesión tenga acceso al contenido de los nodos (organizaciones, divisiones, sitios, etc.) que requiere tu caso de uso.
2. Asegúrate de que el usuario tenga un rol en esos nodos con los permisos que tu integración necesita (leer, editar, gestionar, etc.).

En la pantalla de consentimiento, el usuario también selecciona qué organización autorizar. Los ámbitos que el usuario aprueba allí configuran la capa 1.

Paso 3: autoriza con PKCE

Antes de abrir la página de consentimiento, genera tres valores:

Valor	Cómo
code_verifier	Cadena aleatoria, de 43 a 128 caracteres
code_challenge	BASE64URL(SHA256(code_verifier)) sin relleno
state	Cadena aleatoria; valídala cuando vuelva el redireccionamiento

Abre el navegador del usuario en la página de consentimiento.

URL de consentimiento: https://cloud.prevu3d.com/oauth

Parámetros de consulta (todos obligatorios):

Parámetro	Valor
response_type	code
code_challenge_method	S256
client_id	Tu Client ID
redirect_uri	Tu URI de devolución de llamada HTTPS registrado (coincidencia exacta, sin barra final salvo que esté registrada)
scopes	Uno por ámbito, p. ej. scopes=read:basic&scopes=read:hierarchy
code_challenge	El desafío PKCE de arriba
state	Tu valor de state aleatorio

Después de que el usuario inicie sesión y haga clic en Allow, el navegador redirige a tu devolución de llamada:

https://app.example.com/oauth/callback?code={authorization_code}&state={state}

Si el usuario deniega el acceso, recibes ?error=access_denied en su lugar. Los códigos de autorización caducan a los 60 segundos, así que intercámbialos de inmediato.

Paso 4: intercambia el código por un token de acceso

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

Cabeceras: Content-Type: application/x-www-form-urlencoded

Cuerpo:

Campo	Valor
grant_type	authorization_code
client_id	Tu Client ID
code	Código del redireccionamiento
redirect_uri	El mismo URI usado en el paso 3
code_verifier	El verificador PKCE original
client_secret	Solo si tu app tiene un secreto

Puedes enviar client_id y client_secret en el cuerpo o usar Authorization: Basic base64(client_id:client_secret).

Ejemplo de respuesta:

{
  "hasError": false,
  "expires_in": 86400,
  "access_token": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "..."
}

Guarda ambos tokens. Usa el access_token para las llamadas a la API. Cuando caduque, solicita uno nuevo con grant_type=refresh_token y tu refresh_token almacenado.

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

Llama al endpoint de detección 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, que necesitarás para muchos endpoints.

Paso 6: 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.

Resolución de problemas

Síntoma	Qué comprobar
Discrepancia del Redirect URI en el consentimiento o el intercambio de token	El redirect_uri debe coincidir carácter por carácter con el valor registrado en la app OAuth
URI de redireccionamiento de OAuth no válido al guardar la app	Usa https, un nombre de dominio válido, sin cadena de consulta ni fragmento en el URI registrado
Secreto de la aplicación OAuth incorrecto	Incluye client_secret solo si la app se creó con un secreto
El intercambio del grant caducó	Los códigos de autorización caducan a los 60 segundos; reinicia el flujo
403 en las llamadas a RCAPI	Puede que al usuario le falte acceso al contenido, un rol de nodo o el ámbito de OAuth para la operación

¿Necesitas un redireccionamiento loopback para una app de escritorio o CLI? Usa el flujo de aplicación nativa en su lugar.

¿Qué sigue?

• Flujo de aplicación nativa para localhost / PKCE sin un dominio personalizado
• Flujo de Client Credentials para acceso de servidor a servidor
• Referencia interactiva de la API para el catálogo completo de endpoints