Documentation

Quickstart

Four steps from nothing to a working licence check.

Add RudeAuth licensing to my <language> app.
Read https://docs.rudeauth.com/llms.txt for how RudeAuth works, and follow the
rudeauth-<lang> SDK's AGENTS.md rules: no bool is_licensed(), embed the public key,
verify before trust, no offline cache, and gate real logic into a server-delivered
payload. My app id is <APP_ID> and my public key is <PUBLIC_KEY>.

How verification works

A client never trusts the network. Instead of asking "am I licensed?" and believing the answer, it checks a signature it can verify offline.

• Signed responses. Every reply is Ed25519-signed by your application's key. The signature covers the exact response bytes and the endpoint name, so a reply from one endpoint cannot be replayed as another's.
• Device binding. A licence binds to hardware using K-of-N matching, so replacing a disk does not lock your customer out, but copying the key to another machine does not work.
• Replay protection. Each handshake carries a client nonce, remembered server-side for the length of the clock-skew window. Capturing a successful response and replaying it fails.
• Session keys. The handshake performs an X25519 exchange. Variables and files come back sealed to that session, so they are useless if captured.

Verifying a response

Every endpoint returns the same envelope:

1. RequestFresh nonce and device proof
2. EnvelopeData bytes and signature
3. VerifyEd25519 public key
4. ParseOnly after acceptance

{
  "data": "<base64 of the JSON payload>",
  "signature": "<base64 Ed25519 signature>"
}

Verify the signature over the raw decoded bytes of data, using your application's public key, before parsing anything inside it. Parsing first and verifying second defeats the purpose.

The signature is domain-separated by endpoint name, so a valid handshake response cannot be presented as a files response.

The SDK does this for you. If you are writing your own client, it is the one part you must not skip: an unverified envelope is just JSON from the network.

One exception. A request that cannot be attributed to an application, a malformed body, or an unknown app_id, is answered with an unsigned {"error":"BAD_REQUEST"} and HTTP 400. There is no signing key to sign it with. Treat any unsigned response as a failure.

Handshake

Redeems a licence key, binds the device, and opens a session. Called once per launch.

Request

Response payload

{
  "success": true,
  "client_nonce": "<echoed back>",
  "server_time": 1788134400,
  "session_token": "<base64>",
  "session_expires_at": 1788135300,
  "session_id": "<uuid>",
  "server_eph_pubkey": "<base64>",
  "license": {
    "level": 1,
    "expires_at": 1790726400,
    "devices_used": 1,
    "max_devices": 3
  }
}

Derive the session key with X25519 against server_eph_pubkey, using session_id as HKDF info. The server never stores your ephemeral private key.

On failure, success is false and error holds one of the error codes. The response is still signed.

Heartbeat

Confirms a session is still valid and extends it. Call periodically if your software runs for a long time. Revoking a licence kills its sessions, and the heartbeat is how a running client learns that.

{ "success": true, "valid": true, "server_time": 1788134400, "expires_at": 1788135300 }

valid: false means the session was revoked or expired. Stop the protected functionality, do not retry until the next handshake.

Variables

Fetches server-side values, sealed to the session.

Returns sealed: base64 ciphertext, opened with the session key.

Know the limit. A variable reaches the client, so a determined user can read it out of memory. Variables are worth using for values that rotate, an endpoint that moves, a key that changes weekly, not for a secret that must never be seen.

Files

Delivers an encrypted payload that never shipped inside your binary. The strongest gate available: a customer without a valid licence never receives the bytes at all.

Returns sealed and version. An unknown name returns FILE_NOT_FOUND, which is distinct from a licence failure. Check for it explicitly rather than reporting "invalid licence" for a typo in a filename.

Device reset

Lets a customer unbind their own devices, subject to the cooldown and lifetime cap you set. This is the single most common support request any licensing system receives, a customer replaced a motherboard, and exposing it in your software saves you answering it.

Returns RESET_UNAVAILABLE when the cooldown has not elapsed or the lifetime cap is spent. An operator can always reset from the dashboard, which bypasses both.

Webhook

Invokes an endpoint you configured as client callable, through RudeAuth. Your client never learns the destination URL, and the outbound request is SSRF-guarded and never follows redirects.

Endpoints not marked client-callable cannot be reached this way; they only receive events RudeAuth sends, listed below.

Events

An endpoint receives an event only if it is subscribed to it. Put the event names in the endpoint's Events field in the dashboard, comma separated. An endpoint with an empty Events field receives nothing and exists only to be called through the proxy above.

Every body has the same envelope. data carries the fields for that event.

{
  "event": "device.bound",
  "at": "2026-08-21T09:14:22Z",
  "data": {
    "license_id": "8f1c...",
    "device_id": "2b40...",
    "devices_used": 2,
    "max_devices": 3
  }
}

A body carries ids and counts, never a licence key, a session token or a fingerprint. A webhook lands in your logs, and often in a third party's, so there is nothing in one worth stealing from there. To turn an id into detail, read it back through the Management API or the dashboard, both of which are authenticated.

Delivery retries with backoff for up to ten attempts. Respond 2xx to acknowledge; anything else is a retry. Treat events as at-least-once and make your handler idempotent, since a retry after a timeout you actually processed is indistinguishable from a first delivery.

Error codes

Returned in the signed payload's error field. Match on the code, never the message. Messages are for humans and may change.

Deliberate ambiguity. A missing application and a disabled one both return APP_DISABLED; an unknown key and a malformed one both return LICENSE_INVALID, and take the same code path so timing does not distinguish them either. Precise errors here would be a free oracle for anyone enumerating keys.

Device fingerprints

Send several independent identifiers. RudeAuth hashes each one before it touches the database. Raw values are never stored.

Useful components: CPU ID, motherboard serial, disk serial, MAC address, machine GUID.

• Minimum: set per application. A handshake with fewer is refused.
• Maximum 16. More is rejected. Real fingerprints are a handful of values, and an unbounded list is an unbounded row.
• Matching is K-of-N. Enough components must agree, not all of them, so a replaced disk does not lock a customer out.

Avoid values shared across machines. A virtualised disk serial can be identical on thousands of unrelated PCs. Bans on such a component reach far beyond the machine you meant, which is why the dashboard warns before letting you do it.

Rate limits

Limits apply per application and per source address. Exceeding one returns RATE_LIMITED.

A normal client handshakes once per launch and heartbeats occasionally, so it will not come close. If you are hitting the limit, something is retrying in a loop. Fix the retry, do not raise the ceiling.

Back off exponentially. Retrying immediately makes it worse for every one of your customers.

Something unclear or wrong here? It is a bug in the documentation, and worth reporting as one.