🔑API Authentication

DevPayr’s API authentication is built for distributed software — software that runs outside your control, on customer machines, servers, domains, or devices. Because of this, authentication in DevPayr is explicit by design. Nothing is inferred, guessed, or auto-detected.

Every request to DevPayr must clearly answer three questions:

1. Who is making the request?

2. What authority do they have?

3. Where is this software running?

DevPayr answers these questions using License Keys, API Keys, and an explicit runtime identifier (called domain for simplicity).

Base URL

All requests are made against:

https://api.devpayr.dev/api/v1/

This base URL applies to SDKs, raw HTTP requests, cURL, Postman, and server-to-server integrations.

Authentication Types

DevPayr supports two authentication mechanisms. They serve different purposes and should not be confused.

1. License Key Authentication (Runtime)

License Keys authenticate running software.

They are used inside applications you distribute to customers — web apps, desktop software, plugins, self-hosted tools, or internal deployments.

When a License Key is validated, DevPayr checks:

• That the license exists

• That it belongs to the correct project

• That it is active (not revoked or suspended)

• That it has not expired

• That it is allowed for the provided runtime identifier

• That usage limits are not exceeded

• That the environment is valid (test vs production)

Even if a project is marked as paid, a revoked or expired license will always fail validation.

2. API Key Authentication (Backend)

API Keys authenticate your backend systems.

They are used to manage DevPayr resources programmatically, such as:

• Creating and updating projects

• Issuing licenses after payment

• Revoking or reactivating licenses

• Managing domains and environments

• Fetching injectables

• Checking project payment status

API Keys must never be exposed in frontend or distributed code.

Runtime Identifier (Domain / Device / Fingerprint)

Every runtime validation in DevPayr must include a runtime identifier. This identifier tells DevPayr where the software is running.

Although the header is called X-DevPayr-Domain, the value is not limited to web domains.

It can be:

• A website domain or subdomain

• A desktop machine fingerprint

• A hashed hardware ID

• A server instance ID

• A container or deployment identifier

• Any stable string that uniquely identifies a runtime

DevPayr treats this value as an opaque identifier. No format is enforced.

If the identifier changes, DevPayr treats it as a different device or runtime.

Explicit Domain Requirement (Important)

DevPayr does not auto-detect or guess the runtime identifier.

Whether you are using an SDK or raw HTTP requests, you must explicitly define the domain/runtime identifier.

This ensures:

• Predictable behavior

• Strong license enforcement

• No accidental domain leakage

• Clear audit trails

• Better resistance to piracy

Authentication Using SDKs (Recommended)

SDKs simplify request handling, but they do not infer the runtime identifier. You must explicitly provide it during bootstrap.

The SDK will then attach the correct headers to every request.

PHP SDK Example

<?php

require_once 'vendor/autoload.php';

use DevPayr\DevPayr;
use DevPayr\Exceptions\DevPayrException;

try {
    DevPayr::bootstrap([
        'license'         => 'YOUR-LICENSE-KEY',
        'domain'          => 'device-fingerprint-9f3a2c',
        'base_url'        => 'https://api.devpayr.dev/api/v1/',
        'injectables'     => false,
        'invalidBehavior' => 'modal', // modal | redirect | silent | log
    ]);

    echo "License validated successfully.";
} catch (DevPayrException $e) {
    echo "DevPayr error: " . $e->getMessage();
}

Node.js SDK Example

import { DevPayr } from '@xultech/devpayr';

DevPayr.bootstrap({
  license: 'YOUR-LICENSE-KEY',
  domain: 'device-fingerprint-9f3a2c',
  base_url: 'https://api.devpayr.dev/api/v1/',
  injectables: false,
  invalidBehavior: 'modal',
  onReady: (response) => {
    console.log('License validated:', response);
  },
});

Python SDK Example

from devpayr import DevPayr

DevPayr.bootstrap({
    "license": "YOUR-LICENSE-KEY",
    "domain": "device-fingerprint-9f3a2c",
    "base_url": "https://api.devpayr.dev/api/v1/",
    "injectables": False,
    "invalidBehavior": "log",
    "onReady": lambda data: print("License validated:", data),
})

SDK Behavior Summary

• The domain value is mandatory

• The SDK forwards it as X-DevPayr-Domain

• The SDK does not modify or infer the value

• Changing the value is treated as a new runtime

⚠️ Important — Always Set the Base URL

Always define the base_url explicitly when using DevPayr.

DevPayr may introduce new API versions or provide project-specific endpoints. If the base URL is not set, your integration may break or point to the wrong endpoint.

Set it once, stay in control, and avoid surprises.

Authentication Using Raw HTTP Requests

When not using an SDK, all headers must be supplied manually.

Mandatory Headers (Runtime Requests)

• X-DevPayr-Domain — runtime identifier

• One of:

  • X-LICENSE-KEY (runtime validation)

  • X-API-KEY (backend access)

Requests missing the runtime identifier will be rejected.

License Key Validation (Raw HTTP)

curl -X POST "https://api.devpayr.dev/api/v1/project/has-paid" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-LICENSE-KEY: DP-XXXX-XXXX-XXXX" \
  -H "X-DevPayr-Domain: device-fingerprint-9f3a2c" \
  -d '{
    "include": "injectables"
  }'

If the license is inactive, revoked, expired, or not allowed for that runtime identifier, validation will fail.

API Key Authentication (Raw HTTP)

curl -X GET "https://api.devpayr.dev/api/v1/project/42/has-paid?action=check_project" \
  -H "Accept: application/json" \
  -H "X-API-KEY: YOUR-API-KEY" \
  -H "X-DevPayr-Domain: backend-server-01"

API Keys are validated independently of licenses and are always scoped by ownership and permissions.

Using API Keys and License Keys Together

A common production flow looks like this:

1. Customer completes payment in your system

2. Your backend uses an API Key to issue or activate a license

3. The license key is delivered to the customer

4. The customer’s software validates itself using:

   • The license key

   • An explicit runtime identifier

This separation ensures that:

• Backend automation stays secure

• Distributed software cannot manage licenses

• Runtime usage is fully traceable

Security and Best Practices

• Always provide a stable runtime identifier

• Never rely on auto-detection

• Never expose API Keys in distributed code

• Treat License Keys as revocable credentials

• Rotate API Keys periodically

• Prefer SDKs for consistency and safety

Summary

• License Keys authenticate running software

• API Keys authenticate backend systems

• A runtime identifier is always required

• SDKs forward the identifier — they do not guess it

• Raw HTTP requests must include all headers explicitly

• License state always overrides project payment state

Once authentication succeeds, DevPayr automatically enforces domain rules, device limits, environment constraints, usage tracking, and payment status.