Integration API Overview

The Integration API is the primary interface for external applications to validate licenses, manage activations, check entitlements, and report usage. All endpoints are authenticated via API key and rate-limited.

Base URL

https://api.validonx.com/api/v1/integration

Authentication

All requests require the X-API-Key header:

X-API-Key: vx_your_api_key_here

See API Key Authentication for details on obtaining and managing keys.

Endpoints

Method	Path	Description
POST	/licenses/{licenseKey}/validate	Validate a license key
POST	/activations	Create a device activation
POST	/activations/{activationId}/validate	Validate an existing activation
POST	/entitlements/check	Check feature entitlements
POST	/usage/record	Record usage metrics

Middleware Stack

Every request passes through:

1. ResolveTenantFromApiKey — resolves tenant from API key
2. EnforceRateLimit — enforces per-key rate limits (default: 1,000/hour)

Response Format

Success:

{
  "data": { ... },
  "meta": {
    "request_id": "uuid",
    "api_version": "1"
  }
}

Error:

{
  "error": {
    "code": "LICENSE.NOT_FOUND",
    "message": "License key not found.",
    "type": "license",
    "status": 404,
    "details": {}
  },
  "meta": {
    "request_id": "uuid",
    "api_version": "1"
  }
}

Rate Limits

1,000 requests per hour per API key. See Rate Limits.

Security Model

• API keys are hashed with HMAC-SHA256 before storage
• Raw keys are shown only once at creation
• Each key is bound to one tenant
• Suspended tenants are rejected with 403
• All requests are rate-limited
• last_used_at is updated on every request