Visão Geral

O DVS usa o OAuth2 client credentials grant para autenticação. Toda request à API precisa incluir um Bearer access token no header Authorization. A autorização é ainda mais restrita por authorities embutidas nos claims do token.

Componentes

OSIGU Auth Server

Emite access tokens via OAuth2. Endpoint: https://sandbox.osigu.com/v1/oauth/token.

DVS API

Valida o Bearer token em cada request e aplica authorities + escopo de tenant.

Fluxo de alto nível

1. 1Obter credenciais no onboarding

   A OSIGU provisiona um client_id e um client_secret. Armazene-os no secret manager (Vault, AWS Secrets Manager, etc.). Nunca faça commit no controle de versão.

2. 2Trocar credenciais por um access token

   Faça POST no endpoint de OAuth token com HTTP Basic auth (client_id:client_secret) e grant_type=client_credentials como parâmetro de query string. Será retornado um access_token opaco válido por ~24 horas por padrão, mais um mapa extensions com metadados de tenant (ex.: provider_slug).

3. 3Chamar endpoints do DVS com o token

   Envie o token no header Authorization: Bearer <token>. Faça cache em memória e renove ~60 segundos antes da expiração — não chame o endpoint do OAuth a cada request da API.

4. 4DVS valida token e authorities

   O DVS valida o token contra o Auth Server em cada request (com um cache de curta duração) e aplica as authorities configuradas para a operação solicitada. Retorna 401 se o token for inválido ou expirado, 403 se a conta não tiver a authority requerida.

O que vem na response do token

O access token em si é uma string opaca (não é um JWT) — não é possível decodificá-lo no client. A identidade e os metadados do tenant são retornados ao lado do token no payload da response:

{
  "access_token": "7dd4f350-676e-4257-9d7b-f3c5ac4dfi14",
  "token_type": "bearer",
  "expires_in": 86399,
  "scope": "read write",
  "extensions": {
    "provider_slug": "br-gamma"
  }
}

Campo	Descrição
access_token	Token opaco. Envie como Authorization: Bearer <token> em cada chamada à DVS API.
expires_in	Tempo de vida em segundos (~24h por padrão).
scope	Scope OAuth2 grosso. As authorities específicas do DVS são aplicadas server-side com base na configuração do client_id — veja Authorities.
extensions.provider_slug	Slug do tenant (ex.: br-gamma). Utilize-o para logging e correlação com o suporte da OSIGU.
extensions.*	A OSIGU pode adicionar mais campos de metadados escopados ao tenant ao longo do tempo. Sempre tolere chaves desconhecidas.

O DVS valida o token chamando seu Auth Server em cada request da API (com cache de curta duração). Não é necessário verificar nada no client.

Escopo por tenant

O DVS usa o tenant_slug (do claim do token) para garantir que:

• Só seja possível visualizar e fazer retry das próprias requests de classification/validation.
• Só seja possível validar combinações (document_type, country_code, agreement_code) que a OSIGU explicitamente concedeu.
• Eventos de webhook sejam entregues aos endpoints de webhook registrados, nunca aos de outro tenant.

A identidade do tenant (provider_slug) é vinculada server-side ao client_id — o DVS a deriva do token, nunca do body da request. Isso previne tenant spoofing.

Próximos passos

Obter Tokens

O fluxo exato do OAuth2 client credentials com exemplos de código.

Referência de Authorities

Lista completa de authorities e quais endpoints elas liberam.