Sell accounts and API keys

​

How it works

​

Before you start

• A plan that is not pay-as-you-go — a subscription, subscription_usage, credit, or free_trial plan (plans and pricing). Pay-as-you-go buyers pay per call and leave nothing behind, so there is no account to create.
• A signing secret. ZeroClick signs every call with it and you verify that signature. Create one in the dashboard and keep its id (the kid) and value in your secret manager (keys and secrets).
• An HTTPS endpoint. By default it is /zeroclick/access on the origin of your upstream base URL; you can point it somewhere else.
• Durable storage for accounts, the last version you applied, the credit you have granted in total, and your API key hashes.

pnpm add @zeroclickai/sellers

pip install zeroclick-sellers

go get cdn.zeroclick.io/sdks/sellers-go

bundle add zeroclick-sellers

​

The three ids, and which one to key on

• agentId (agt_…) is the per-call caller identity — the same id your stateless endpoints see as zc-agent-id. A customer’s human can hold several agents, and any of them may act on the account, so different calls to one account may carry different agent ids. Verify it, log it, but never key on it.
• buyerId (byr_…) appears once the caller’s credential has been claimed by its human — the same value proxied traffic carries as zc-buyer-id. Not a key either, but worth an ordinary column if you also keep buyer-keyed customer records: it is what joins this account to them.

{ remintPolicy: "rotating" }

​

Tying the account to a user account

• requested — the recommended default when you want the email. Purchases are never blocked. When the buying agent is already claimed by a human with a verified email, the account write carries it immediately; when the agent is still anonymous, the purchase goes through without it, and ZeroClick calls your endpoint again the moment the human claims — a fresh account write, one stateVersion higher, identical except that buyerEmail is now set. Your existing write handler needs nothing new: apply the newest picture as always, and treat a buyerEmail appearing partway through an account’s life as your cue to link.
• required — ZeroClick refuses the purchase (403 verified_email_required) until the claim exists, so every write for the account carries the email from the first version. Use it only when you cannot deliver anything without an email; it costs you the fully autonomous purchase.

• The email matches an existing user — attach the ZeroClick account (and the key you later mint) to that user, so the purchase shows up in the account they already have with you.
• The email is new — create a fresh user account for it, exactly as if they had signed up on your site, and provision the ZeroClick purchase into it.
• You would rather wait — store the email against the accessId and link the resource when the human registers or signs in with that address later; until then the agent still uses the minted key normally.

​

Build the endpoint

import { handleAccessRequest } from "@zeroclickai/sellers/stateful";

const options = {
  basePath: "/zeroclick/access",
  remintPolicy: "rotating" as const,
  secrets: {
    [process.env.ZEROCLICK_SIGNING_SECRET_KID!]:
      process.env.ZEROCLICK_SIGNING_SECRET!,
  },
  onHandlerError: (error: unknown, operation: "write" | "mint") => {
    logger.error({ error, operation }, "ZeroClick access handler failed");
  },
};

export async function handle(request: Request): Promise<Response> {
  const rawBody = new Uint8Array(await request.clone().arrayBuffer());
  const url = new URL(request.url);

  const result = await handleAccessRequest(
    {
      method: request.method,
      pathAndQuery: `${url.pathname}${url.search}`,
      rawBody,
      headers: Object.fromEntries(request.headers),
    },
    { onWrite, onMint },
    options,
  );

  // Not one of ZeroClick's two routes: let your own router handle it.
  if (result === null) return new Response("Not found", { status: 404 });

  return new Response(
    result.body === undefined ? null : JSON.stringify(result.body),
    {
      status: result.status,
      headers: {
        ...(result.body === undefined
          ? {}
          : { "content-type": "application/json" }),
        ...result.headers,
      },
    },
  );
}

​

Create the account

1. Ignore anything you have already applied. shouldApply compares the incoming stateVersion against the one you stored.
2. Never grant the same credit twice. lifetimeCreditGrantedUsd is a running total, not the size of this top-up, so you add the difference. deriveCreditDelta computes it and tells you which of three cases you are in.

import { deriveCreditDelta, shouldApply } from "@zeroclickai/sellers/stateful";
import type { WriteInput } from "@zeroclickai/sellers/stateful";

async function onWrite({ accessId, entitlement }: WriteInput) {
  await database.transaction(async (tx) => {
    const account = await tx.lockAccount(accessId);
    if (!shouldApply(account?.stateVersion, entitlement.stateVersion)) return;

    const delta = deriveCreditDelta(
      account
        ? {
            stateVersion: account.stateVersion,
            lifetimeCreditGrantedUsdMicros:
              account.lifetimeCreditGrantedUsdMicros,
            lifetimeCreditReversedUsdMicros:
              account.lifetimeCreditReversedUsdMicros,
          }
        : null,
      entitlement,
    );

    if (delta.outcome === "credit") {
      await tx.addCredit(accessId, delta.deltaUsdMicros);
      await tx.storeGrant(accessId, delta.next);
    } else if (delta.outcome === "debit") {
      // A refund or dispute clawed money back; clamp the balance at zero.
      await tx.subtractCredit(accessId, delta.deltaUsdMicros);
      await tx.storeGrant(accessId, delta.next);
    } else if (delta.outcome === "no_credit_dimension") {
      await tx.storeGrant(accessId, delta.next);
    }

    await tx.applyPlanAndPeriod(accessId, entitlement);

    // Recommended: link the account to your own user account whenever the
    // verified email is present — it can arrive on a later write than the
    // first (see "Tying the account to a user account" above).
    if (entitlement.buyerEmail) {
      await tx.linkAccountToUser(accessId, entitlement.buyerEmail);
    }
  });

  return { lifecycle: "active" as const };
}

​

Mint the key

import type { MintInput } from "@zeroclickai/sellers/stateful";

async function onMint({ accessId }: MintInput) {
  const plaintext = generateApiKey();
  const digest = hashApiKey(plaintext);

  const created = await database.transaction(async (tx) => {
    const account = await tx.lockActiveAccount(accessId);
    if (!account) return false;

    // Required when remintPolicy is "rotating"; skip it for additive keys.
    await tx.revokeLiveKeys(account.id);
    await tx.insertKeyHash(account.id, digest);
    return true;
  });

  return created ? { apiKey: plaintext } : { unknown: true as const };
}

• Return the plaintext exactly once and store only a hash. ZeroClick passes the key to the buyer and keeps no copy, so nobody can look it up again.
• Hash it appropriately. For a random key with real entropy — 32 bytes from a CSPRNG or better — a plain SHA-256 is right: fast enough to check on every request, with nothing to brute-force. Reach for a slow KDF like Argon2 only if your keys are short or human-chosen.
• Never log it, and keep it out of error messages. The SDK already sets cache-control: no-store.
• Revoke and insert in one transaction when rotating, or a retry can leave the customer with two live keys or none.

​

Decide whether to serve

import { isServiceable } from "@zeroclickai/sellers/stateful";

if (!isServiceable(account.state)) {
  return refuseInYourOwnErrorShape(account);
}

• suspended is recoverable. Suspend service and delete nothing; a later write may return the account to active.
• closed is terminal. ZeroClick sends it when the account is torn down on the ZeroClick side: revoke live API keys, stop serving, and keep your own records. No higher stateVersion will ever follow.

​

When a customer runs out of credit

https://acme.pay.zeroclick.io/extend?accessId=zacc_8h2m4x0q9k1f

​

Retries and failures

• You have 7 seconds to respond. Commit, then answer. Anything slower belongs behind lifecycle: "provisioning".
• Return 503 — or just throw — for anything temporary. ZeroClick retries network errors, 429, and any 5xx, backing off for up to 24 hours. It does not retry other 4xx responses, so a bug that returns 400 permanently fails the delivery.
• A permanent failure refunds the buyer automatically. A reserved payment is released, a captured one refunded. You never owe a refund for an account you did not create.

​

Customers with more than one agent

​

Before you go live

• Serve the endpoint over HTTPS, with no redirects.
• Verify signatures against the raw body bytes and the original path and query.
• Look up secrets by kid and keep the previous one through a rotation.
• Never route these requests through guard, guardIdentity, or verifyRequest.
• Apply stateVersion and credit in one locked transaction, and never lower a recorded total.
• Store key hashes only, return plaintext once, keep keys out of logs.
• Make rotation revoke-and-insert atomic.
• Gate every authenticated request on isServiceable — period expiry has no push.
• Return 503 for anything temporary; remember other 4xx responses are permanent.
• Alert on handler errors and on repeated retries for the same account.
• Test a duplicate write, an out-of-order write, a handler timeout, a repeated key request, and a signing-secret rotation.

​

Next steps