Fluxo Client Credentials

Use o fluxo Client Credentials para integrações servidor a servidor que agem em nome da sua organização sem um usuário conectado. Este guia mostra a configuração da criação do aplicativo OAuth até a primeira chamada à API.

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 seu aplicativo no Prevu3D e obtenha credenciais
Configurar o acesso do usuário de serviço — Dê ao seu aplicativo acesso aos dados de que ele precisa
Obter um token de acesso — Autentique-se e receba um token para usar a API
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.
Escolha Client Credentials como fluxo OAuth.
Atribua as permissões de que seu aplicativo precisa (isso configura a camada 1: escopos OAuth). O administrador da sua organização pode ajudar a decidir quais escopos são necessários.
Clique no botão de criar.
Copie e armazene com segurança seu Client ID e Client Secret. Você precisará deles em cada requisição à API.

Etapa 2: configurar o acesso do usuário de serviço

Quando você cria um aplicativo OAuth, um usuário de serviço correspondente é criado automaticamente na sua organização. Esse usuário de serviço representa seu aplicativo ao interagir com a API, mas ainda não tem nenhum acesso.

Esta etapa cobre as camadas 2 e 3 do modelo de segurança: quais nós o usuário de serviço pode ver (acesso ao conteúdo) e o que ele pode fazer com eles (acesso por função/permissão).

Vá em Settings → Users.
Encontre seu usuário de serviço e clique no botão de editar (ele deve ter um nome semelhante ao do aplicativo OAuth que você criou).
Conceda ao usuário de serviço acesso ao conteúdo dos nós (organizações, divisões, sites etc.) que seu caso de uso exige.
Atribua a função/permissão apropriada nesses nós para que o usuário de serviço possa realizar as operações necessárias (ler, editar, gerenciar etc.).
Confirme as alterações.

Etapa 3: obter seu token de acesso

Para chamar a API, você primeiro precisa de um token de acesso. Envie uma requisição ao endpoint de token com seu Client ID e Client Secret.

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

Cabeçalhos:

Authorization: Basic <base64(client_id:client_secret)> — Codifique seu Client ID e Secret como client_id:client_secret e, em seguida, faça a codificação Base64 dessa string
Content-Type: application/x-www-form-urlencoded

Corpo: grant_type=client_credentials

Exemplo de requisição:

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

Exemplo de resposta:

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

Salve o accessToken da resposta. O token é válido por 1 hora; depois disso, você precisará solicitar um novo da mesma forma.

Etapa 4: obter a URL base da sua API

RealityConnect API regional (sua organização usa uma região; este guia explica como descobrir a URL exata):

Chame o endpoint de descoberta abaixo 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 — você precisará dele em muitos endpoints.

Etapa 5: 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.

Experimente com Python

Aqui está um script completo que faz tudo o que foi descrito acima. Substitua client_id e client_secret pelas suas credenciais e execute-o.

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

Solução de problemas

Se você vir…	Tente isto…
401 Unauthorized ao obter um token	Confira seu Client ID e Secret. Verifique se você está fazendo a codificação Base64 de `client_id:client_secret` corretamente.
403 Forbidden ao chamar a API	Uma requisição precisa passar pelas três camadas de segurança. Verifique se (1) seu aplicativo OAuth tem os escopos corretos, (2) o usuário de serviço tem acesso ao conteúdo do nó de destino e (3) ele tem uma função com as permissões necessárias nesse nó.

Para problemas de conexão, DNS e URL da API, consulte Primeiros passos — URLs da API e acesso de rede.

Próximos passos

Adicione lógica para renovar seu token antes de ele expirar (após 1 hora).
Explore a referência da API para conhecer todas as operações disponíveis.