DEV Community

Zero Heartbeat
Zero Heartbeat

Posted on Edited on Originally published at delta1labs.com

Bulk-provisioning licenses through the Keyright admin API

A single POST /v1/admin/licenses per customer is the right shape for everyday fulfillment: a payment clears, your webhook handler issues one license, done. It stops being the right shape the day a sales team closes a 2,000-seat enterprise agreement and someone needs every one of those seats provisioned before the kickoff call — or when you onboard a reseller whose catalog seeds a few hundred licenses at once.

Run that as a loop of 2,000 individual POSTs and two problems surface immediately. It is slow — a few hundred milliseconds of round-trip each, serialized, is minutes of wall-clock time and a lot of connection churn. Worse, it is fragile in the middle: if the job dies at item 1,742 — a network blip, a process restart, a deploy — you are left guessing which licenses exist and which do not, and a naive re-run risks minting 1,741 duplicates. The fix is the admin API's batch endpoint, which issues many licenses in one request, reports a result for every item, and is safe to re-run.

Key takeaway: Provision in bulk with POST /v1/admin/licenses:batch instead of a POST-per-license loop. Give the request a batch-level Idempotency-Key and each item its own idempotencyKey (derived from your record id) plus an externalId for the join back. The endpoint processes items independently and returns a per-item result — created, duplicate, or failed — so a bad record never rolls back the good ones and you retry only the failures. For thousands of items, use the async form: the POST hands back a job id, you poll the job until completed, then read the same per-item results.

Why the naive loop hurts

The loop looks fine in a script and falls over in production:

// ANTI-PATTERN: one POST per customer, no idempotency, no partial-failure story.
foreach (var seat in enterpriseDeal.Seats)          // 2,000 iterations
{
    var resp = await http.PostAsJsonAsync("/v1/admin/licenses", new {
        product = "acme-suite", edition = "pro", customer = seat.CustomerId });
    resp.EnsureSuccessStatusCode();                 // throws → loop dies mid-batch
}
Enter fullscreen mode Exit fullscreen mode

EnsureSuccessStatusCode() turns the first transient 503 into an exception that aborts the loop, and because nothing records which seats already succeeded, your only recovery is to start over — re-issuing licenses for every customer processed so far. You can bolt per-item idempotency onto this loop (and you should, if a loop is all you have), but you are still paying 2,000 serialized round-trips and getting 2,000 independent success/failure signals you have to stitch together yourself.

The batch endpoint

One request carries an array of items. The request gets a batch-level Idempotency-Key; each item gets its own idempotencyKey and an externalId that ties it to your record.

POST /v1/admin/licenses:batch HTTP/1.1
Host: licensing.example.com
Authorization: Bearer {admin_token}
Idempotency-Key: deal-ACME-2026-11-15
Content-Type: application/json

{
  "defaults": { "product": "acme-suite", "edition": "pro", "seats": 1 },
  "items": [
    { "externalId": "crm:row_8831", "licensee": "ana@acme.example",
      "entitlements": { "export": "true" }, "idempotencyKey": "crm:row_8831" },
    { "externalId": "crm:row_8832", "licensee": "ben@acme.example",
      "idempotencyKey": "crm:row_8832" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

defaults applies to every item so you do not repeat product and edition 2,000 times; any field set on an item overrides the default. The response is a multi-status: an overall 207, with a result object per item in the same order you sent them.

HTTP/1.1 207 Multi-Status
Content-Type: application/json

{
  "created": 1,
  "duplicate": 1,
  "failed": 0,
  "results": [
    { "externalId": "crm:row_8831", "status": "created",
      "licenseId": "lic_7f3a9c2e" },
    { "externalId": "crm:row_8832", "status": "duplicate",
      "licenseId": "lic_41b0d8a7" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Three per-item outcomes, and the distinction is the whole point:

  • created — a new license was minted; licenseId is yours to persist.
  • duplicate — an item with this idempotencyKey was already issued; the existing license id is returned and nothing new is minted. This is what makes a re-run safe.
  • failed — the item was rejected (a missing required field, a malformed licensee); a reason and code say why. The other items are unaffected.

A provisioning client that re-runs safely

The vendor-side helper does four things: chunk your records into batches, send each batch, collect the per-item results, and write the license ids back to your system of record. Chunking matters — one request of 2,000 items is a lot to hold open, and a few hundred per batch keeps each request quick while still cutting round-trips by two orders of magnitude.

public sealed class LicenseProvisioner(HttpClient http)
{
    const int ChunkSize = 200;

    public async Task<ProvisionReport> ProvisionAsync(
        IReadOnlyList<SeatRecord> seats, CancellationToken ct)
    {
        var report = new ProvisionReport();

        foreach (var chunk in seats.Chunk(ChunkSize))
        {
            var body = new BatchRequest
            {
                Defaults = new() { Product = "acme-suite", Edition = "pro", Seats = 1 },
                Items = chunk.Select(s => new BatchItem
                {
                    ExternalId     = s.CrmRowId,          // join key back to your CRM
                    Licensee       = s.Email,
                    IdempotencyKey = s.CrmRowId,          // same key makes re-runs safe
                }).ToArray(),
            };

            using var req = new HttpRequestMessage(HttpMethod.Post, "/v1/admin/licenses:batch");
            req.Headers.Add("Idempotency-Key", $"deal-{DealId}-{chunk[0].CrmRowId}");
            req.Content = JsonContent.Create(body);

            // Retrying the whole chunk is safe: created items come back as `duplicate`.
            var resp = await Resilience.Pipeline.ExecuteAsync(
                async t => await http.SendAsync(req, t), ct);

            var batch = await resp.Content.ReadFromJsonAsync<BatchResponse>(ct);
            foreach (var r in batch!.Results)
                report.Record(r);                         // persist licenseId or log failure
        }

        return report;
    }
}
Enter fullscreen mode Exit fullscreen mode

Because every item carries an idempotencyKey derived from a stable record id, re-running the whole ProvisionAsync call — after a crash, a half-finished batch, or simply because a nightly reconciliation runs again — never duplicates. Items that were already issued come back as duplicate with their original license id; only genuinely new records are created. You get the failed subset straight from report and can re-submit just those once the underlying record is fixed.

Large volumes: the async job

Above a few hundred items, prefer the async form so you are not holding a single HTTP request open while thousands of licenses are minted. Add "mode": "async" and the endpoint returns a job id instead of inline results:

POST /v1/admin/licenses:batch HTTP/1.1
Authorization: Bearer {admin_token}
Idempotency-Key: deal-ACME-2026-11-15

{ "mode": "async", "defaults": { "product": "acme-suite", "edition": "pro" },
  "items": [ /* 2,000 items */ ] }
Enter fullscreen mode Exit fullscreen mode
HTTP/1.1 202 Accepted
{ "jobId": "job_b914f27c", "status": "pending", "total": 2000 }
Enter fullscreen mode Exit fullscreen mode

Poll the job until it settles, then read the same per-item results you would have gotten synchronously:

BatchResponse job;
do
{
    await Task.Delay(TimeSpan.FromSeconds(2), ct);
    job = await http.GetFromJsonAsync<BatchResponse>(
        $"/v1/admin/jobs/{jobId}", ct);
}
while (job!.Status is "pending" or "running");

foreach (var r in job.Results) report.Record(r);   // created / duplicate / failed, as before
Enter fullscreen mode Exit fullscreen mode

The job is addressable by id, so polling survives a restart of your provisioning process: you persist the jobId, and if your worker dies you resume polling the same job rather than re-issuing. The batch-level Idempotency-Key guarantees that even submitting the same batch twice returns the same job rather than starting a second one.

The customer's side: nothing special

All of the above produces ordinary licenses — bulk issuance is a vendor convenience, not a different license type. Each provisioned seat validates through the SDK exactly like a single-issued one, offline against the embedded public key:

var client = KeyrightClient.Initialize(new KeyrightOptions
{
    Product         = "acme-suite",
    PublicKeyBase64 = Embedded.PublicKey,     // ships in your binary; not a secret
    ServiceUrl      = "https://licensing.example.com",
});

LicenseInfo info = client.Validate();          // offline, never throws
if (!info.IsValid || !info.IsEnabled("acme.export"))
    return Gate.Deny("Export requires an active license.");
Enter fullscreen mode Exit fullscreen mode

The end user never knows whether their seat was one of two or one of two thousand. That separation — bulk on the issuing side, identical verification on the client side — is what lets you onboard an enterprise deal in a single reconcilable operation without changing a line of the gating code your customers run.

Throughput, briefly

Two practical limits shape how you pace a large rollout. Keep chunks in the low hundreds so each request stays fast and the per-item result array stays easy to handle. And drive the batches with a small bounded concurrency rather than a thousand parallel requests — a short queue of two or three in-flight batches is plenty to saturate the issuing service's throughput without tripping its rate limits. When a batch comes back rate-limited, your resilience pipeline's retry-with-jitter handles it, and because the batch is idempotent the retry is free of duplicates.

That is the whole shape of bulk provisioning done right: one idempotent batch call per chunk, a per-item result you can reconcile against your records by externalId, an async job for the large rollouts, and a re-run that is always safe because every item knows its own identity. The 2,000-seat deal becomes one operation you can run, inspect, and run again — not a fragile loop you hope finishes.

Top comments (0)