🌐Domains / Devices / IP Restrictions

Licensing is not just “does this key exist?” — it’s also where that key is being used, how many places it’s being used, and from where in the world it’s being called. That’s what this page is about.

DevPayr lets you bind a license to real-world context: domains, devices, IP addresses, and countries. This is how you stop a single key from powering 50 copies of your product, or a “one-site” license mysteriously running on 12 servers around the world.

This page will walk you through:

• how DevPayr knows where your app is running

• how domain and device restrictions work

• how IP and country restrictions are enforced

• how to use these controls safely from the SDKs and via raw HTTP

All in plain language, with no magic.

1. The core idea: “Where is this copy running?”

Every validation request to DevPayr answers two big questions:

1. Who are you? → the license key

2. Where are you running? → the domain / device / fingerprint

The license key is obvious. The second part — the domain / device / fingerprint — is what we send via a single concept DevPayr expects on every runtime validation:

X-Devpayr-Domain “A stable identifier that represents where this copy of your software is running.”

Despite the name, this value does not have to be a literal URL or domain. It can be:

• a real web domain (saas-client.com, app.customer.io)

• a subdomain (tenant1.app.com)

• an internal hostname (intranet.local)

• a device fingerprint or machine hash

• a container / instance ID

• any opaque string that consistently represents this installation

From DevPayr’s point of view, this value is the “place” you’re licensing: a domain if it’s a web app, a machine if it’s a desktop app, an instance ID if it’s a self-hosted deployment.

When you use the SDKs, they can infer this automatically (for web/server contexts), and you can also override it explicitly if you want full control. When you use raw HTTP or cURL, you must send it yourself as a header.

2. How the SDKs send domain / device identifiers

When you bootstrap any DevPayr SDK, you give it enough information to identify the license and the environment. The SDK then takes care of talking to DevPayr, sending the license key and the “where am I running?” identifier.

PHP SDK

<?php

require_once 'vendor/autoload.php';

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

try {
    DevPayr::bootstrap([
        'license'         => 'YOUR-LICENSE-KEY',
        'injectables'     => true,
        'invalidBehavior' => 'modal', // Options: modal, redirect, silent, log

        // Optional: explicitly tell DevPayr where this copy runs
        // e.g. 'myclient-app.com' or a machine/instance fingerprint
        'domain'          => 'myclient-app.com',
    ]);

    // Your protected logic continues here...
    echo "License valid. Project is paid.";
} catch (DevPayrException $e) {
    // Handle critical exceptions
    echo "DevPayr error: " . $e->getMessage();
}

If you do not provide the domain option, the SDK will attempt to infer it automatically (for example, from the host or environment in web contexts). If you do provide it, that value becomes the identifier DevPayr tracks and enforces against for this license.

Node.js SDK

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

DevPayr.bootstrap({
  license: 'your-license-key-here',
  secret: 'your secret key', // for injectables
  base_url: 'https://api.devpayr.com',
  action: 'boot',
  injectables: true,
  invalidBehavior: 'modal', // or 'redirect', 'silent', 'log'

  // Optional: explicit identifier for this installation
  // Can be a domain, hostname, or fingerprint
  domain: 'client1.example.com',

  onReady: (response) => {
    console.log('✅ License Valid:', response);
  },
});

Again, if you do not specify domain, the SDK will detect what it can. If you care about binding a license tightly to a specific host or fingerprint, always set it yourself.

Python SDK

from devpayr import DevPayr

DevPayr.bootstrap({
    "license": "your-license-key",          # Required if using license mode
    "api_key": "your-api-key",             # Optional: for advanced API operations
    "base_url": "https://api.devpayr.com/api/v1/",
    "secret": "your-shared-secret",        # For decrypting injectables
    "injectables": True,
    "handleInjectables": True,
    "injectablesVerify": True,
    "injectablesPath": "./dev_injectables",
    "invalidBehavior": "modal",            # modal, redirect, log, silent
    "redirectUrl": "https://yourdomain.com/upgrade",
    "customInvalidMessage": "License check failed. Please contact support.",

    # Optional: installation identifier (domain / device / fingerprint)
    "domain": "myclient-server-01",
})

Same pattern: domain is your hook for declaring which installation this is. DevPayr treats that value as the “place” where the license is being used.

3. Domain-level restrictions: one license, specific places

Domain restrictions let you say, in human terms:

• “This license is only allowed on this domain.”

• “This license can be used on up to 3 distinct domains.”

• “This license can be used on 1 domain with up to 5 subdomains.”

From DevPayr’s point of view, every time a license is validated it sees:

• the license key

• the identifier you’ve sent (in domain or X-Devpayr-Domain)

DevPayr then compares that identifier against the rules you configured:

• Pinned to a specific domain If you bind a license to a single domain (for example, when issuing it in the dashboard), DevPayr will only accept validations where the identifier matches that domain exactly. This is perfect for “one-site license” or “this SaaS instance belongs to client X only”.

• Limited to a small number of domains If the license allows multiple domains (for example, 3 sites for an agency package), DevPayr will track which identifiers have been associated with that license. Once the license has reached its maximum domain count, any new identifier will be rejected.

• Subdomain limits per base domain For some products you want something like: “You can run on app.client.com, admin.client.com, and api.client.com, but not on 50 random subdomains.” DevPayr allows you to set a limit on how many subdomains of the same base domain can be associated with a license. Once that per-domain subdomain limit is reached, additional subdomains will be blocked.

• Unlimited domains or subdomains For higher-tier or custom plans, you can mark domains or subdomains as unlimited. In that case, the license behaves like a “floating” license with no domain cap, but you still benefit from validation, payment checks, environments, and other policies.

If a validation comes in from a domain or identifier that violates any of these rules, DevPayr will respond with an error and your SDK will treat it as an invalid licensing context. You can then decide how your app behaves — lock the UI, switch to “unlicensed” mode, or show a clear “license not allowed on this domain” message.

4. Devices and fingerprints: when there is no domain

Not all software runs behind a nice clean domain name. You might have:

• a desktop app running on Windows, macOS, or Linux

• a CLI tool running on servers or developer machines

• an internal tool running entirely on localhost

• a background service running inside containers

In these environments, the concept of “domain” doesn’t really exist, but the problem is the same: you want to limit how many places a license can run and where it is allowed.

The solution is to treat domain as a generic installation identifier rather than literally a URL. In your app, you compute or choose a stable identifier such as:

• a machine ID or OS-level fingerprint

• a hardware hash

• a hashed combo of hostname + user ID

• an instance UUID stored in a config file

You then pass that value as domain in the SDK configuration (or as X-Devpayr-Domain if you’re calling the API directly). DevPayr does not care what the string looks like; it only cares that it is consistent and that it obeys the license’s rules.

From there, all the same concepts apply:

• one license can be pinned to a specific fingerprint

• you can allow a small number of devices per license

• you can treat each device as a “domain” from DevPayr’s perspective

DevPayr doesn’t see inside your fingerprint — it only sees “this string == this installation” and enforces limits based on that, which also means you can hash or obfuscate it and avoid exposing sensitive system details.

5. Test vs production environments

Environments exist for a simple reason: you don’t want your developers and staging servers competing with real customers for license slots, and you don’t want test licenses to accidentally power real-world deployments.

In practice, this usually works like:

• For test licenses:

  • You use them on local machines, .test domains, or dedicated staging hosts.

  • DevPayr is more permissive in development-style environments so developers can move quickly.

  • If someone tries to use a test license on a real production domain, DevPayr will reject it.

• For production licenses:

  • They are not meant to be used on test or staging domains.

  • If someone tries to drag a production license back into a staging environment, DevPayr can block this as well, so your environment boundaries remain clean.

The exact environment configuration and labels are set in DevPayr when you define domains and licenses. From your app side, the key point is: continue to send the correct identifier for the environment you’re running in, and DevPayr will enforce whether that license is allowed to run there or not.

6. IP and country restrictions

Sometimes domain or device checks are not enough. You may need to comply with regional restrictions, protect internal tools, or limit a license to a very specific network or office.

For that, licenses can also carry IP and country restrictions:

• Allowed IPs You can list one or more IP addresses that are allowed to use the license. If this list is present, DevPayr will compare the incoming request’s IP against that list. If the IP is not in the allowed set, the request is rejected. This is useful for internal systems, office-only tools, or extremely sensitive deployments.

• Allowed countries You can also specify a list of allowed countries. DevPayr will resolve the incoming IP into a country code and check whether it appears in the allowed list. If not, the license validation fails with an “access from this country is not allowed” style error. This is handy for compliance (e.g., export restrictions) or for products that are only sold in certain regions.

These checks are optional and can be combined with domain or device restrictions. If you don’t configure them, DevPayr will not block by IP or country. If you do, they become an extra layer of guardrails around your license.

Use them carefully — a too-strict IP rule can lock legitimate users out if they move networks or switch hosting providers, and a too-tight country rule can break legitimate roaming users. They are powerful tools, but more “surgical strike” than “default setting”.

7. Raw HTTP and the X-Devpayr-Domain header

When you’re not using an SDK — for example, when you are calling DevPayr from a language without an official SDK or from an integration layer — you must manually supply both:

• the license or API key, and

• the installation identifier (X-Devpayr-Domain).

A typical pattern looks like this for license-based validation:

curl -X POST "https://api.devpayr.dev/api/v1/project/has-paid" \
  -H "Accept: application/json" \
  -H "X-LICENSE-KEY: DP-XXXX-XXXX-XXXX" \
  -H "X-Devpayr-Domain: clientapp.example.com" \
  -d '{"include":"injectables"}'

Or, when using an API key on a project-scoped endpoint:

curl -X GET "https://api.devpayr.dev/api/v1/project/42/has-paid?action=check_project&include=injectables" \
  -H "Accept: application/json" \
  -H "X-API-KEY: YOUR_API_KEY_HERE" \
  -H "X-Devpayr-Domain: clientapp.example.com"

In both cases:

• the license key or API key tells DevPayr who is asking

• the X-Devpayr-Domain header tells DevPayr where this is running

Without X-Devpayr-Domain, DevPayr will not be able to tie the request to a real-world installation, and the request will be treated as invalid.

If your app is not domain-based (e.g., a desktop app), simply send a stable fingerprint instead of a domain. The name of the header stays the same; the meaning is “this is the identifier for this instance”.

8. Practical patterns and recommendations

To keep things sane and predictable as your product grows, here are some battle-tested recommendations:

• Always send a deliberate identifier Don’t rely forever on automatic detection. Pick your identifier strategy (domain, hostname, fingerprint) and set it explicitly in the SDK config. That way you know exactly what DevPayr is enforcing.

• Use domain binding for client web projects For agency / freelancer work where you deploy to client domains, bind licenses either to a single domain or a small number of domains. This is the simplest and most intuitive approach.

• Use fingerprints for desktop / internal tools If your app runs on devices or internal networks, generate and store a stable fingerprint per installation and use that as the identifier.

• Keep IP and country rules as “extra locks,” not the first lock Start with domain/device rules. Add IP/country restrictions only when there is a clear business or legal reason.

• Be honest with your customers about limits If a license is “1 domain only” or “up to 3 devices,” say it clearly in your pricing and product copy. DevPayr will enforce that; your docs and contracts should match.

When you think about DevPayr’s restrictions, the mental model is simple:

The license answers “who is allowed.” The identifier (domain/device/fingerprint) answers “where it’s allowed.” IP and country answer “from where it’s allowed to be used.”

Everything else is just policy layered on top of those three questions.