Visión general

DVS utiliza el grant_type OAuth2 client credentials para autenticación. Toda request a la API debe incluir un Bearer access_token en el header Authorization. La autorización se afina adicionalmente mediante authorities asociadas a las credenciales.

Componentes

OSIGU Auth Server

Emite access tokens vía OAuth2. Endpoint: https://sandbox.osigu.com/v1/oauth/token.

DVS API

Valida el Bearer token en cada request y aplica las authorities + el alcance por tenant.

Flujo de alto nivel

1. 1Obtener credenciales en el onboarding

   OSIGU aprovisiona un client_id y client_secret. Almacenarlos en un gestor de secrets (Vault, AWS Secrets Manager, etc.). Nunca commitearlos al control de versiones.

2. 2Intercambiar credenciales por un access token

   Hacer POST al endpoint OAuth de token con HTTP Basic auth (client_id:client_secret) y grant_type=client_credentials como parámetro en el query string. Se recibe un access_token opaco válido por ~24 horas por defecto, más un mapa extensions con metadatos del tenant (p. ej., provider_slug).

3. 3Llamar a los endpoints de DVS con el token

   Enviar el token en el header Authorization: Bearer <token>. Cachearlo en memoria y refrescarlo ~60 segundos antes de la expiración — no golpear el endpoint OAuth en cada llamada a la API.

4. 4DVS valida token y authorities

   DVS valida el token contra el Auth Server en cada request (con un caché de vida corta) y aplica las authorities configuradas para la operación solicitada. Devuelve 401 si el token es inválido o expiró, 403 si la cuenta carece de la authority requerida.

Qué contiene la response del token

El access_token en sí es una cadena opaca (no un JWT) — no es posible decodificarlo del lado del cliente. La identidad y los metadatos del tenant se devuelven junto al token en el payload de la response:

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

Campo	Descripción
access_token	Token opaco. Enviarlo como Authorization: Bearer <token> en cada llamada a la API de DVS.
expires_in	Tiempo de vida en segundos (~24h por defecto).
scope	Scope OAuth2 grueso. Las authorities específicas de DVS se aplican del lado del servidor según la configuración del client_id — ver Authorities.
extensions.provider_slug	El slug del tenant (p. ej., br-gamma). Usarlo para logging y para correlacionar con el soporte de OSIGU.
extensions.*	OSIGU podrá agregar más campos de metadatos por tenant con el tiempo. Tolerar siempre claves desconocidas.

DVS valida el token llamando a su Auth Server en cada request a la API (con un caché de vida corta). No es necesario verificar nada del lado del cliente.

Alcance por tenant

DVS utiliza el tenant_slug (del claim del token) para aplicar lo siguiente:

• Solo es posible ver y reintentar las requests de classification/validation propias.
• Solo es posible validar combinaciones de (document_type, country_code, agreement_code) que OSIGU haya otorgado explícitamente.
• Los eventos de webhook se entregan a los endpoints propios registrados, nunca a los de otro tenant.

La identidad del tenant (provider_slug) está vinculada del lado del servidor al client_id — DVS la deriva del token, nunca del body de la request. Esto previene el spoofing de tenant.

Próximos pasos

Obtener Tokens

El flujo exacto de OAuth2 client credentials con ejemplos de código.

Referencia de Authorities

Lista completa de authorities y qué endpoints habilitan.