Revoking a leaked license key across every client
A key got shared, dumped on a paste site, or is activating from three continents at once. Here is the practical playbook: how you revoke it in Keyright, what revocation means server-side, and — the part most teams get wrong — how deployed SDK clients actually learn about it and stop working.
Every licensing system has a bad day that looks like this. A support ticket mentions a license key you do not recognize on an account you do. Your abuse dashboard lights up because one key activated from Lisbon, then from São Paulo eleven minutes later. Or someone pastes a key straight into a public gist with the caption “works, enjoy.” The key is real, it was issued correctly, and the signed license file on every machine that has it still validates perfectly. Expiry will not save you — that is months away. You need to revoke it, and you need every client holding it to find out and stop.
This post is the end-to-end playbook: detecting the abuse that justifies revocation, performing the revocation against your Keyright deployment, what revocation actually changes server-side, and — the part that decides whether any of this matters — how a deployed SDK client learns its key is dead and fails closed.
Why revocation is a different problem from expiry
It helps to be precise about what a signed license is. When Keyright issues a key, the client receives a license payload signed with your product’s private key; the SDK verifies it offline against the public key you pin. That signature is the whole point — it means a client can trust a license without phoning home on every single call. Expiry rides inside that payload, so a client enforces it with zero network.
Revocation breaks that comfortable model on purpose. You are making a decision after the license was signed: this specific key, valid signature and all, should no longer work. Nothing in the bytes the client already holds reflects that. The signature still checks out. The only way a client can discover the revocation is to ask the authority that made the decision — your issuing service — or to rely on a cached answer that is allowed to go stale. That single fact drives everything below, including why the revalidation interval is the most important setting you will touch.
Step 0: detect the abuse worth revoking
Revocation is a response, so the trigger matters. A few signals reliably justify it:
- Concurrent-seat overuse. A key licensed for a handful of seats is validating from dozens of distinct machine identities at once. Keyright’s activation records give you the distinct-node count per license; when it runs well past the entitled seat count and stays there, the key has escaped.
- Impossible travel. Two activations from the same key separated by more time zones than minutes. One key cannot be in Lisbon and São Paulo inside a quarter of an hour; two copies of it can.
- Public exposure. The key turns up in a paste site, a committed
.env, a support thread, a forum. Once a key is public, seat counting will not keep up — you revoke and reissue.
You can watch these by hand on the dashboard, or drive them off the activation and validation events the issuing service already records. Either way, the decision to revoke is yours; the mechanics below are the same once you have made it.
Step 1: revoke the key
A vendor revokes a license in one of two equivalent ways. In the dashboard, open the license and choose Revoke — optionally with a reason and whether to lock out immediately or after a short grace window. For automation — say, a fraud job that revokes on a chargeback webhook — call the admin API directly:
POST /v1/admin/licenses/lic_7c1f9a/revoke HTTP/1.1
Host: your-keyright-deployment.example.com
Authorization: Bearer ${KEYRIGHT_ADMIN_TOKEN}
Content-Type: application/json
{
"reason": "leaked_public",
"effective": "immediate"
}
A successful call returns the updated license with its new state:
{
"licenseId": "lic_7c1f9a",
"product": "acme-suite",
"status": "revoked",
"reason": "leaked_public",
"revokedAtUtc": "2026-11-14T09:30:02Z",
"graceUntilUtc": null
}
Setting "effective": "grace" instead would populate graceUntilUtc with a near-future timestamp — more on that tradeoff below.
Step 2: what revocation means server-side
Server-side, revocation does two things. First, it flips the license’s authoritative status to revoked in your issuing service’s records, with a timestamp and reason — this is the source of truth every online check now reads. Second, the key is placed on a denylist: a compact, fast-to-consult set of revoked license identifiers that the validation path checks before it returns a verdict. The denylist exists so that revocation does not require re-reading or re-signing anything; a key’s signature stays mathematically valid forever, and the denylist is what overrides it.
Crucially, the issuing service stops honoring the key for anything new: no fresh activations, no renewals, no seat leases. A revoked license is a closed account.
Step 3: how deployed clients find out
This is where teams either win or quietly fail. You have flipped the server; now every copy of the SDK in the field has to catch up. There are two populations, and they behave differently.
Online clients. Any client that can reach your deployment learns on its next validation. The SDK’s ValidateAsync consults the authoritative status, sees the denylist hit, and returns a result that is no longer valid. If your app revalidates on launch and on a timer — which it should — the window between your revoke and the client failing closed is one revalidation interval, usually minutes. For a key leaked publicly, that is effectively immediate.
Cached and offline clients. The SDK caches its last good verdict so the app survives brief network blips without nagging the user. That cache is governed by the revalidation interval: how long a cached “valid” is allowed to stand before the SDK must re-check against the issuing service. A revoked key keeps working on an offline client right up to the moment that interval elapses and the next check comes back revoked. The interval is therefore a direct dial on your exposure: a 30-day interval means a revoked key can keep working offline for up to 30 days; a 6-hour interval caps it at 6 hours. For high-risk products, pick a short interval and accept the extra check traffic — it is the price of fast propagation.
The sequence below ties the whole chain together: abuse is detected, the vendor revokes, the next online check fails closed, and the offline cache expires at its revalidation boundary.
Step 4: the client-side gating pattern that actually fails closed
None of the server work matters if the app treats a failed validation as a shrug. The rule is blunt: when validation does not clearly succeed, deny the feature. Not “allow on error,” not “allow if we are not sure” — deny. Here is the shape, using genuine Keyright SDK idioms.
using Keyright;
KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-suite",
PublicKeyBase64 = "MCowBQYDK2VwAyEA...", // pinned at build time
ServiceUrl = "https://your-keyright-deployment.example.com",
RevalidationInterval = TimeSpan.FromHours(6) // short = fast revocation propagation
});
var client = KeyrightClient.Current;
public async Task<bool> TryUnlockPremiumExportAsync()
{
var result = await client.ValidateAsync();
// Fail CLOSED: the only path to "true" is an explicitly valid, non-revoked license.
if (!result.IsValid)
{
if (result.Status == LicenseStatus.Revoked)
{
// Authoritative: the key was revoked. Lock the feature and surface a clear message.
_log.Warning("License {Id} revoked ({Reason}); locking premium export.",
result.LicenseInfo?.LicenseId, result.RevocationReason);
ShowRevokedNotice(result.RevocationReason);
}
else
{
// Expired, tampered, unreachable-with-stale-cache, etc. Still denied.
_log.Warning("License not valid ({Status}); denying premium export.", result.Status);
}
return false;
}
// Valid key — now gate on the specific entitlement, not just "has a license."
if (!client.HasEntitlement("premium-export"))
return false;
var info = result.LicenseInfo;
_log.Information("Premium export unlocked for {Customer}.", info?.CustomerRef);
return true;
}
Three details carry the weight. First, the single success path: control only reaches the unlock when IsValid is true and the entitlement is present. Every other branch returns false. Second, the explicit LicenseStatus.Revoked check is for the user experience, not the enforcement — a revoked key deserves a clearer message than a generic failure, but even if you deleted that branch the feature would still lock, because the outer !result.IsValid already denied it. Third, the short RevalidationInterval is doing quiet work: it is the ceiling on how long a cached “valid” can outlive a revocation.
A note on where not to fail closed: do not hard-crash the whole app on a transient network error. The cached-verdict model exists precisely so a brief outage does not brick a paying customer. Fail closed on the feature, keep the app running, and let the next successful revalidation restore access — or confirm the revocation.
Immediate lockout versus grace
Revoking "effective": "immediate" puts the key on the denylist now; the next check anywhere fails closed. That is correct for fraud, chargebacks, and public leaks, where you want the value to stop flowing this minute.
Grace is for the honest-mistake case. A good customer committed their key to a public repo; you want to kill that key but not interrupt their work while they roll to a replacement. Revoking with a short graceUntilUtc lets online clients keep validating until that timestamp, then fails them closed — and you hand the customer a freshly issued key in the meantime. The tradeoff is real: every minute of grace is a minute the leaked key still works for whoever else has it. Reserve grace for low-risk situations and pair it with immediate reissuance; default to immediate for anything that smells like abuse.
The one-paragraph version
Revocation is a post-issuance decision that a valid signature cannot express, so clients must learn it by asking. You revoke through the dashboard or the admin API; server-side the license status flips to revoked and the key joins a denylist the validation path consults. Online clients fail closed on their next ValidateAsync; offline clients keep working only until the revalidation interval expires, so set that interval short for high-risk keys. In the app, make the deny path the default and the unlock the single narrow exception. Do that, and a leaked key is a brief incident instead of an open tap.
Try Nebula.NET
Harden your .NET code in minutes — start with the free edition.