Tenant Resolution & Routing

Every request to the ValidonX API must be resolved to a specific tenant. This document explains how tenant resolution works and what headers are required.

Resolution Paths

Path 1: API Key Resolution (Integration API)

Used for: /v1/integration/* endpoints (license validation, activation, entitlements, usage)

Client → X-API-Key header → HMAC-SHA256 hash → api_keys table lookup → tenant

Required header: X-API-Key: VX-xxxxx...

The middleware:

1. Extracts X-API-Key from the request header
2. Hashes it with HMAC-SHA256 using the application key
3. Looks up the hash in the api_keys table
4. Validates the key is active and the tenant is active
5. Switches the database connection to the tenant's database
6. Binds the tenant to the request

Error responses:

• 401 AUTH.INVALID_API_KEY — missing, invalid, or revoked key
• 403 TENANT.STATUS.SUSPENDED — tenant is suspended

Path 2: User-Based Resolution (Tenant API)

Used for: /v1/tenant/*, /v1/billing/* endpoints

Client → Bearer token → Sanctum auth → user's tenants → X-Tenant-ID (if multiple)

Required header: Authorization: Bearer <token>Optional header: X-Tenant-ID: <uuid> (required if user belongs to multiple tenants)

The middleware:

1. Authenticates via Sanctum (auth:sanctum)
2. Loads the user's active tenants via the tenant_user pivot
3. If single tenant: auto-selects it
4. If multiple tenants: requires X-Tenant-ID header
5. Validates the selected tenant is active
6. Switches the database connection

Common Headers

Header	Required	Description
X-API-Key	Integration API	Tenant API key
Authorization	Tenant/Admin API	Bearer <token>
X-Tenant-ID	Multi-tenant users	UUID of target tenant
X-Request-ID	Optional	Request correlation ID (auto-generated if absent)

Rate Limit Headers (Response)

All Integration API responses include:

Header	Description
X-RateLimit-Limit	Max requests in current window
X-RateLimit-Remaining	Requests remaining
X-RateLimit-Reset	Unix timestamp when window resets
Retry-After	Seconds to wait (429 responses only)