Fluxo Authorization Code + Redirecionamento Personalizado

Use o fluxo Authorization Code + redirecionamento HTTPS personalizado para aplicativos web que agem em nome de um usuário conectado e recebem o callback OAuth no seu próprio domínio. Ele usa Authorization Code com PKCE, uma URI de redirecionamento HTTPS de correspondência exata e um segredo de cliente opcional para clientes confidenciais do lado do servidor.

Consulte primeiro o guia Primeiros passos se você ainda não conhece os pré-requisitos, o acesso de rede e o modelo de segurança.

O que você fará

Criar um aplicativo OAuth: Registre um aplicativo web no Prevu3D com sua URL de callback HTTPS
Configurar o acesso do usuário: Garanta que o usuário que fará login consiga alcançar os dados de que precisa
Autorizar com PKCE: Envie o usuário à página de consentimento no navegador
Trocar o código por um token: Troque o código de autorização por um token de acesso
Encontrar sua URL da API: Descubra a URL base da sua organização (ela varia por região)
Fazer sua primeira chamada: Teste a conexão com uma requisição simples

Etapa 1: criar seu aplicativo OAuth

Faça login na Plataforma Prevu3D.
Vá em Settings → OAuth.
Clique para criar um novo aplicativo.
Ative o Authorization Code flow.
Deixe Native Application desativado.
Informe sua Redirect URI, por exemplo https://app.example.com/oauth/callback. Ela precisa ser HTTPS com um nome de domínio totalmente qualificado e precisa corresponder exatamente na autorização e na troca do token.
Opcionalmente, ative um segredo de cliente se seu aplicativo puder armazená-lo no lado do servidor. Clientes públicos apenas de navegador não devem usar segredo.
Copie e armazene com segurança seu Client ID (e o segredo, se gerado).

Etapa 2: configurar o acesso do usuário

Este fluxo chama a API como o usuário conectado, não como um usuário de serviço. Isso cobre as camadas 2 e 3 do modelo de segurança: quais nós o usuário pode ver (acesso ao conteúdo) e o que ele pode fazer com eles (acesso por função/permissão).

Garanta que o usuário que fará login tenha acesso ao conteúdo dos nós (organizações, divisões, sites etc.) que seu caso de uso exige.
Garanta que o usuário tenha uma função nesses nós com as permissões de que sua integração precisa (ler, editar, gerenciar etc.).

Na tela de consentimento, o usuário também seleciona qual organização autorizar. Os escopos que o usuário aprova ali configuram a camada 1.

Etapa 3: autorizar com PKCE

Antes de abrir a página de consentimento, gere três valores:

Valor	Como
`code_verifier`	String aleatória, de 43 a 128 caracteres
`code_challenge`	`BASE64URL(SHA256(code_verifier))` sem preenchimento
`state`	String aleatória; valide-a quando o redirecionamento retornar

Abra o navegador do usuário na página de consentimento.

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

Parâmetros de consulta (todos obrigatórios):

Parâmetro	Valor
`response_type`	`code`
`code_challenge_method`	`S256`
`client_id`	Seu Client ID
`redirect_uri`	Sua URI de callback HTTPS registrada (correspondência exata, sem barra final, a menos que registrada)
`scopes`	Um por escopo, por exemplo `scopes=read:basic&scopes=read:hierarchy`
`code_challenge`	O desafio PKCE gerado acima
`state`	Seu valor de state aleatório

Depois que o usuário fizer login e clicar em Allow, o navegador redireciona para seu callback:

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

Se o usuário negar o acesso, você receberá ?error=access_denied em vez disso. Os códigos de autorização expiram após 60 segundos, portanto troque-os imediatamente.

Etapa 4: trocar o código por um token de acesso

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

Cabeçalhos: Content-Type: application/x-www-form-urlencoded

Corpo:

Campo	Valor
`grant_type`	`authorization_code`
`client_id`	Seu Client ID
`code`	Código do redirecionamento
`redirect_uri`	A mesma URI usada na Etapa 3
`code_verifier`	O verificador PKCE original
`client_secret`	Somente se seu aplicativo tiver um segredo

Você pode enviar client_id e client_secret no corpo ou usar Authorization: Basic base64(client_id:client_secret).

Exemplo de resposta:

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

Salve os dois tokens. Use o access_token para chamadas à API. Quando ele expirar, solicite um novo com grant_type=refresh_token e seu refresh_token armazenado.

Etapa 5: obter a URL base da sua API

Chame o endpoint de descoberta para obter a apiUrl da sua organização. Não codifique uma URL regional de forma fixa.

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

Cabeçalhos: Authorization: Bearer <your_access_token>

Exemplo de resposta:

{
  "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 o valor de apiUrl como base para todas as suas chamadas à API. Anote também o organization.id, de que você precisará em muitos endpoints.

Etapa 6: fazer sua primeira chamada à API

Agora você tem tudo de que precisa: um token de acesso e sua URL base. Vamos fazer uma requisição simples para recuperar as divisões da sua organização:

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

Exemplo com valores reais:

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

Uma resposta bem-sucedida contendo uma lista de divisões confirma que sua integração está funcionando corretamente.

Solução de problemas

Sintoma	O que verificar
Redirect URI mismatch no consentimento ou na troca do token	A `redirect_uri` precisa corresponder ao valor registrado no aplicativo OAuth caractere por caractere
Invalid OAuth redirect URI ao salvar o aplicativo	Use `https`, um nome de domínio válido, sem query string nem fragmento na URI registrada
Bad OAuth application secret	Inclua `client_secret` apenas se o aplicativo foi criado com um segredo
Grant exchange expired	Os códigos de autorização expiram após 60 segundos; reinicie o fluxo
403 nas chamadas à RCAPI	O usuário pode não ter acesso ao conteúdo, função no nó ou escopo OAuth para a operação

Precisa de um redirecionamento loopback para um aplicativo de desktop ou uma CLI? Use o Fluxo de Aplicativo Nativo em vez disso.

Próximos passos

Fluxo de Aplicativo Nativo para localhost / PKCE sem um domínio personalizado
Fluxo Client Credentials para acesso servidor a servidor
Referência interativa da API para o catálogo completo de endpoints