Authentication

How to authenticate with the OnyxAuth platform.

Two Authentication Methods

The API uses different auth methods depending on the endpoint:

1. Session Cookie (Dashboard & Management API)

Used for browser-based dashboard access and management endpoints (creating/updating/deleting licenses). Handled automatically by Better-Auth after login.

2. No Auth Required (Validation Endpoint)

The POST /api/v1/validate endpoint is public. The license key itself identifies which customer's license to validate. This is by design. Your end-users' software calls this endpoint directly.

API Keys

API keys are used to identify your integration. They are generated from your dashboard.

LIVE

lic_live_...

Production keys. Use these in your shipped software.

TEST

lic_test_...

Test keys for development. Safe to use during integration.

Key Security

•API keys are hashed with BLAKE3 before storage. We never store the plaintext key
•Keys are only shown once at creation, so save them immediately
•Revoke compromised keys instantly from your dashboard
•Never commit API keys to version control

Error Responses

Authentication failures return these error codes:

401 Unauthorizedjson

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Not authenticated"
  }
}

403 Forbidden (upgrade required)json

{
  "success": false,
  "error": {
    "code": "UPGRADE_REQUIRED",
    "message": "This feature requires a Developer plan. Upgrade to access it."
  }
}