Authorization Code + Custom Redirect Flow

Use the Authorization Code + custom HTTPS redirect flow for web applications that act on behalf of a signed-in user and receive the OAuth callback on your own domain. It uses Authorization Code with PKCE, an exact-match HTTPS redirect URI, and an optional client secret for confidential server-side clients.

Review the Getting Started guide first if you have not already covered prerequisites, network access, and the security model.

---

What you’ll do

1. Create an OAuth application: Register a web app in Prevu3D with your HTTPS callback URL
2. Configure user access: Make sure the signing-in user can reach the data it needs
3. Authorize with PKCE: Send the user through the browser consent page
4. Exchange the code for a token: Trade the authorization code for an access token
5. Find your API URL: Discover your organization’s base URL (it varies by region)
6. Make your first call: Test the connection with a simple request

Step 1: Create your OAuth application

1. Log in to the Prevu3D Platform.
2. Go to Settings → OAuth.
3. Click to create a new application.
4. Enable Authorization Code flow.
5. Leave Native Application off.
6. Enter your Redirect URI, for example https://app.example.com/oauth/callback. It must be HTTPS with a fully qualified domain name and must match exactly at authorization and token exchange time.
7. Optionally enable a client secret if your app can store it server-side. Public browser-only clients should not use a secret.
8. Copy and securely store your Client ID (and secret if generated).

Step 2: Configure user access

This flow calls the API as the signed-in user, not a service user. This covers layers 2 and 3 of the security model: which nodes the user can see (content access), and what it can do with them (role / permission access).

1. Make sure the user who will sign in has content access to the nodes (organizations, divisions, sites, etc.) your use case requires.
2. Make sure the user has a role on those nodes with the permissions your integration needs (read, edit, manage, etc.).

On the consent screen, the user also selects which organization to authorize. The scopes the user approves there configure layer 1.

Step 3: Authorize with PKCE

Before opening the consent page, generate three values:

Value	How
code_verifier	Random string, 43 to 128 characters
code_challenge	BASE64URL(SHA256(code_verifier)) without padding
state	Random string; validate it when the redirect comes back

Open the user’s browser to the consent page.

Consent URL: https://cloud.prevu3d.com/oauth

Query parameters (all required):

Parameter	Value
response_type	code
code_challenge_method	S256
client_id	Your Client ID
redirect_uri	Your registered HTTPS callback URI (exact match, no trailing slash unless registered)
scopes	One per scope, e.g. scopes=read:basic&scopes=read:hierarchy
code_challenge	The PKCE challenge from above
state	Your random state value

After the user signs in and clicks Allow, the browser redirects to your callback:

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

If the user denies access, you receive ?error=access_denied instead. Authorization codes expire after 60 seconds, so exchange them right away.

Step 4: Exchange the code for an access token

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

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

Body:

Field	Value
grant_type	authorization_code
client_id	Your Client ID
code	Code from the redirect
redirect_uri	The same URI used in Step 3
code_verifier	The original PKCE verifier
client_secret	Only if your app has a secret

You may send client_id and client_secret in the body or use Authorization: Basic base64(client_id:client_secret).

Example response:

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

Save both tokens. Use the access_token for API calls. When it expires, request a new one with grant_type=refresh_token and your stored refresh_token.

Step 5: Get your API base URL

Call the discovery endpoint to get the apiUrl for your organization. Do not hardcode a regional URL.

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

Headers: Authorization: Bearer <your_access_token>

Example response:

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

Use the apiUrl value as the base for all your API calls. Also note the organization.id, which you will need for many endpoints.

Step 6: Make your first API call

You now have everything you need: an access token and your base URL. Let’s make a simple request to retrieve your organization’s divisions:

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

Example with real values:

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

A successful response containing a list of divisions confirms that your integration is working correctly.

Troubleshooting

Symptom	What to check
Redirect URI mismatch at consent or token exchange	redirect_uri must match the value registered on the OAuth app character for character
Invalid OAuth redirect URI when saving the app	Use https, a valid domain name, no query string or fragment in the registered URI
Bad OAuth application secret	Include client_secret only if the app was created with a secret
Grant exchange expired	Authorization codes expire after 60 seconds; restart the flow
403 on RCAPI calls	User may lack content access, node role, or OAuth scope for the operation

Need a loopback redirect for a desktop app or CLI? Use the Native Application Flow instead.

What’s next?

• Native Application Flow for localhost / PKCE without a custom domain
• Client Credentials Flow for server-to-server access
• Interactive API reference for the full endpoint catalog