Skip to main content

Authentication & Authorization

Current Model: License-Based System Authorization​

Kulpay API uses a license key to authorize the system itself, rather than individual API requests. The license is validated at the middleware level on every incoming request — however, there is no Authorization header required on API calls. The system holds the license internally and validates it against the database on each request.

How It Works​

The License Interceptor middleware runs before every request reaches the service layer. It checks the currently activated license key stored in the system against the database, verifying that the license is active, not expired, and has the required capabilities.

License Lifecycle​

StateDescription
activeLicense is valid and the system can serve requests
expiredLicense has passed its expiration date; requests are rejected
invalidLicense has been deactivated or revoked

License Activation​

Before the system can serve requests, a license must be activated:

curl -X POST https://host:8080/v1/license/activate \
  -H "Content-Type: application/json" \
  -d '{"license_key": "your_license_key_here"}'

Response:

{
  "license_key": "your_license_key_here"
}

Once activated, the license key is stored by the system and validated automatically on every request. No further authentication action is needed from the API consumer.

License Information​

Retrieve information about the active license:

curl -X GET https://host:8080/v1/license

Response:

{
  "license": {
    "id": "jti_abc123",
    "status": "active",
    "issued_to": "partner_bank",
    "issuer": "kulpay",
    "issued_at": "2025-01-01T00:00:00Z",
    "expires_at": "2026-01-01T00:00:00Z"
  }
}

License Validation​

Validate a license key without activating it:

curl -X POST https://host:8080/v1/license/validate \
  -H "Content-Type: application/json" \
  -d '{"license_key": "your_license_key_here"}'

Response:

{
  "valid": true,
  "message": "License is valid",
  "license": {
    "id": "jti_abc123",
    "status": "active",
    "issued_to": "partner_bank",
    "issuer": "kulpay",
    "issued_at": "2025-01-01T00:00:00Z",
    "expires_at": "2026-01-01T00:00:00Z"
  }
}

Background Revalidation​

The system periodically re-verifies the license in the background. In development, this occurs every 30 seconds to ensure rapid feedback. If the license expires or is revoked externally, the system will stop serving requests at the next revalidation cycle.

Per-Request User Authentication​

Planned Feature

Per-request user authentication (e.g., Bearer tokens, API keys per consumer) is planned but not yet implemented. Currently, all API requests are authorized solely through the system-level license. This section will be updated when user-level authentication is introduced.

Error Responses​

401 Unauthorized​

Returned when no valid license is active in the system.

{
  "code": "unauthorized",
  "message": "No valid license key provided",
  "request_id": "req_abc123"
}

Technical Decision: License Over Per-Request Auth​

The license-based model was chosen for the initial release because Kulpay API operates as a middleware service deployed within the partner's infrastructure. The license validates that the deployment itself is authorized, rather than authenticating individual end-users. This simplifies integration — client applications can call the API without managing tokens or sessions. Per-request authentication will be layered on top as the platform scales to multi-tenant scenarios.