Skip to content
← All posts
· Delta1 Labs SupportKeyright

Why is this customer's license blocked?

A support engineer gets a ticket saying a license "won't activate", but the client is fail-closed and only ever reports "blocked". Here is a read-only diagnosis tool, built on the Keyright admin API, that replays the whole verification pipeline in explain mode and reports exactly which gate failed — expiry, revocation, machine binding, a seat lease, or a missing entitlement — without ever exposing the key.

A support engineer opens a ticket: “Customer ACME says the app won’t activate — it just says the license is blocked.” That is all the information there is, because a correctly built license client is designed to give nothing more. It fails closed, denies access, and reports one opaque state. The engineer now has to work out whether the subscription lapsed, the key was revoked, the seats are all taken, the customer moved to a new machine, or they are simply on a plan that never included the feature they are trying to use — and they have to do it without the one artifact that would make it trivial and dangerous to share: the signed key.

This is a solvable problem, and the solution is not to make the client chattier. It is a small, read-only diagnosis tool that talks to the issuing service over the Keyright admin API and replays the verification pipeline in a mode that explains instead of enforcing.

The client answers one question; support needs a different one

Verification inside the client is a short-circuiting pipeline. It runs a fixed sequence of gates — is the signature authentic, is “now” inside the validity window, is the key on the revocation list, is this the machine the license is bound to, is there a free seat, does the license grant the feature being asked for — and the moment one gate fails, it stops and denies. It never evaluates the gates after the failure, because it does not need to: the answer is already no.

// Inside the client: fail-closed, short-circuiting, deliberately opaque.
LicenseInfo info = client.Validate();   // offline, never throws
if (!info.IsValid)
    return Gate.Deny("This copy is not licensed. Contact your administrator.");

info.IsValid is a single boolean. The user sees “not licensed”. That is the correct behaviour for an enforced binary, and it is exactly why support cannot work from it. The question support needs answered is not “is this blocked” — they already know it is — but “which gate failed, and why”. Answering that means running the same pipeline against the authoritative record on the issuing service, but with the short-circuit turned off, so every gate reports its own verdict instead of the first failure swallowing the rest.

verification pipeline (one order, two readers)diagnosis verdict1 · signatureRSA over canonical payloadPASSauthentic2 · date windownotBefore ≤ now ≤ notAfterPASSnot expired3 · revocationnot on blocklistPASSactive4 · machine bindingfingerprint matchesPASSbound host5 · seat leasea seat is free to claimFAIL5 of 5 seats in use6 · entitlementfeature.export grantedUNKNOWNclient stopped at 5client Validate() returns Blocked here →↑ never evaluated by the client

A read-only diagnose endpoint

The issuing service already holds the authoritative record for every license: its validity window, whether it has been revoked, which machine it is bound to, and how many of its seats are currently leased. The admin API exposes a read-only diagnose view of that record. It takes a non-secret handle — a license id, or a short key fingerprint the customer can read off their About screen — and optionally a machine fingerprint the customer reported, so the node-binding gate can be evaluated too.

GET /v1/admin/licenses/lic_7f3a9c2e/diagnose?machine=fp_9b21c4 HTTP/1.1
Host: licensing.example.com
Authorization: Bearer {admin_read_token}

The response is the pipeline, evaluated in full. Each gate carries its own verdict — pass, fail, or unknown — and a fail carries a machine-readable code plus a human detail. Crucially, nothing short-circuits: the fail on the seat gate does not stop the entitlement gate from reporting, except where a gate genuinely cannot be evaluated server-side.

{
  "licenseId": "lic_7f3a9c2e",
  "keyFingerprint": "KR…c4e1",
  "product": "acme-suite",
  "edition": "pro",
  "overall": "blocked",
  "checks": [
    { "gate": "signature",  "verdict": "pass" },
    { "gate": "dateWindow", "verdict": "pass", "expiresOn": "2027-03-01T00:00:00Z" },
    { "gate": "revocation", "verdict": "pass" },
    { "gate": "machine",    "verdict": "pass", "detail": "Reported fingerprint matches the bound host." },
    { "gate": "seat",       "verdict": "fail", "code": "seats_exhausted",
      "detail": "5 of 5 seats are leased. Oldest lease expires in 00:11:42." },
    { "gate": "entitlement","verdict": "unknown",
      "detail": "Not reached by the client; not evaluated without a requested feature." }
  ]
}

The read token is the important word. This endpoint is GET-only and the token scope grants nothing but reads — it cannot revoke, re-bind, extend, or free a seat. A support engineer who can diagnose should not, by holding that ability, also be able to silently hand out free capacity. Remediation is a separate, audited action behind a different scope.

The support tool

With a read-only endpoint, the tool itself is thin: fetch the diagnosis, render the checklist, and lead with the first failing gate — because that is the one the client actually stopped on and the one the customer is hitting.

public sealed class LicenseDoctor(HttpClient admin)
{
    public async Task<Diagnosis> LookUpAsync(string handle, string? machine, CancellationToken ct)
    {
        var url = $"/v1/admin/licenses/{Uri.EscapeDataString(handle)}/diagnose";
        if (machine is not null) url += $"?machine={Uri.EscapeDataString(machine)}";
        return (await admin.GetFromJsonAsync<Diagnosis>(url, ct))!;
    }

    public static void Print(Diagnosis d)
    {
        Console.WriteLine($"License {d.KeyFingerprint}  ({d.Product}/{d.Edition})  →  {d.Overall.ToUpper()}");
        foreach (var c in d.Checks)
        {
            var mark = c.Verdict switch
            {
                "pass"    => "[ok]  ",
                "fail"    => "[FAIL]",
                _         => "[?]   ",
            };
            Console.WriteLine($"  {mark} {c.Gate,-12} {c.Detail}");
        }

        var cause = d.Checks.FirstOrDefault(c => c.Verdict == "fail");
        if (cause is not null)
            Console.WriteLine($"\nRoot cause: {cause.Gate} — {cause.Code}\n{cause.Detail}");
    }
}

public sealed record Diagnosis(string LicenseId, string KeyFingerprint, string Product,
    string Edition, string Overall, IReadOnlyList<Check> Checks);
public sealed record Check(string Gate, string Verdict, string? Code = null, string? Detail = null);

Run against the ACME ticket, it prints the whole story at a glance:

License KR…c4e1  (acme-suite/pro)  →  BLOCKED
  [ok]   signature
  [ok]   dateWindow    expires 2027-03-01
  [ok]   revocation
  [ok]   machine       Reported fingerprint matches the bound host.
  [FAIL] seat          5 of 5 seats are leased. Oldest lease expires in 00:11:42.
  [?]    entitlement   Not reached by the client; not evaluated without a requested feature.

Root cause: seat — seats_exhausted
5 of 5 seats are leased. Oldest lease expires in 00:11:42.

The ticket is now answered in one line: ACME is not broken, lapsed, or on the wrong plan — they have simply used every seat they bought, and a lease frees in eleven minutes. The engineer tells them to either wait, close a session, or buy more seats, and no one spends an afternoon chasing an expiry that was never the problem.

Reading the entitlement gate

The one gate that reads unknown by default is the entitlement check, and the reason is worth stating plainly: entitlements are evaluated against a feature the app asked for. The diagnose view does not know which feature the customer was reaching for, so it cannot say whether that specific grant is present until you tell it. Pass the feature key and it resolves:

GET /v1/admin/licenses/lic_7f3a9c2e/diagnose?feature=feature.export HTTP/1.1
{ "gate": "entitlement", "verdict": "fail", "code": "not_granted",
  "detail": "This license grants max_projects=10 but not feature.export (Standard edition)." }

Those keys — feature.export, max_projects, max_major_version — are the vendor’s own entitlement names, carried in the signed grant and surfaced verbatim. The diagnosis reads them straight from the authoritative record, so “the customer swears they paid for export” resolves instantly into “their edition does not include it” — a sales conversation, not a bug.

Caveats, and the line the tool must not cross

Three limits keep this honest. First, the tool is read-only by contract: diagnosis and remediation are different scopes, so the ability to explain a block is never the ability to quietly undo one. Second, two gates depend on facts the server does not own — the machine fingerprint and the local clock live on the customer’s host, so the diagnosis can only mark them pass/fail when the customer reports them and otherwise returns unknown. A healthy server record plus a blocked customer is the tool’s way of pointing at exactly those two things: a moved machine or a skewed clock. Third, the diagnosis is a snapshot at the time support runs it — a seat that was exhausted at 14:02 may be free by 14:05 — so the lease timings it prints are guidance, not a guarantee.

And the line it must not cross: the key never enters the flow. The tool identifies a license by id or fingerprint, the response echoes only a fingerprint, and the support transcript that outlives the ticket carries nothing a reader could activate with. A diagnosis tool exists to turn “it just says blocked” into “seats exhausted, frees in eleven minutes” — to make the fail-closed client legible to a human — while giving away exactly as little as the client itself does.

Try Nebula.NET

Harden your .NET code in minutes — start with the free edition.