Overview

DVS uses OAuth2 client credentials grant for authentication. Every API request must include a Bearer access token in the Authorization header. Authorization is further scoped by authorities embedded in the token claims.

Components

OSIGU Auth Server

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

DVS API

Validates the Bearer token on every request and enforces authorities + tenant scoping.

High-level flow

1. 1Obtain credentials at onboarding

   OSIGU provisions you a client_id and client_secret. Store them in your secret manager (Vault, AWS Secrets Manager, etc.). Never commit to source control.

2. 2Exchange credentials for an access token

   POST to the OAuth token endpoint with HTTP Basic auth (client_id:client_secret) and grant_type=client_credentials as a query string parameter. Receive an opaque access_token valid for ~24 hours by default, plus an extensions map with tenant metadata (e.g., provider_slug).

3. 3Call DVS endpoints with the token

   Send the token in the Authorization: Bearer <token> header. Cache it in memory and refresh ~60 seconds before expiry — don't hit the OAuth endpoint on every API call.

4. 4DVS validates token and authorities

   DVS validates the token against the Auth Server on every request (with a short-lived cache) and enforces the configured authorities for the requested operation. Returns 401 if the token is invalid or expired, 403 if your account lacks the required authority.

What's in the token response

The access token itself is an opaque string (not a JWT) — you cannot decode it client-side. Tenant identity and metadata are returned alongside the token in the response payload:

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

Field	Description
access_token	Opaque token. Send as Authorization: Bearer <token> on every DVS API call.
expires_in	Lifetime in seconds (~24h by default).
scope	Coarse OAuth2 scope. DVS-specific authorities are enforced server-side based on your client_id configuration — see Authorities.
extensions.provider_slug	Your tenant slug (e.g., br-gamma). Use it for logging and to correlate with OSIGU support.
extensions.*	OSIGU may add more tenant-scoped metadata fields over time. Always tolerate unknown keys.

DVS validates the token by calling its Auth Server on every API request (with a short-lived cache). You don't need to verify anything client-side.

Tenant scoping

DVS uses your tenant_slug (from the token claim) to enforce that:

• You can only see and retry your own classification/validation requests.
• You can only validate (document_type, country_code, agreement_code) combinations that OSIGU explicitly granted you.
• Webhook events are delivered to your registered webhook endpoints, never another tenant's.

Your tenant identity (provider_slug) is bound server-side to your client_id — DVS derives it from the token, never from the request body. This prevents tenant spoofing.

Next steps

Obtain Tokens

The exact OAuth2 client credentials flow with code samples.

Authorities Reference

Full list of authorities and which endpoints they unlock.