API key exchange

The API key exchange is the one endpoint you must host for ZeroClick. When a buyer purchases a plan, ZeroClick calls it to trade the buyer's identity for an API key in your system. When a plan ends, ZeroClick calls it again to revoke that key. Only ZeroClick can call this endpoint: every request is signed, and you must reject requests that fail verification.

Provision a key#

Called when a buyer purchases a plan, or extends a plan after a lapse.

Request body

{
	"userId": "user_8f3kz1",
	"plan": "pln_starter_monthly"
}

Response 200 OK

{
	"apiKey": "sk_live_b64x..."
}

The key should be valid immediately: ZeroClick injects it into the buyer's very next proxied request.

Revoke a key#

Called when a plan expires, is cancelled, or a renewal payment fails. The request body is the same shape (userId and plan). Invalidate the key you issued for that buyer and return 200 OK. After revocation, ZeroClick stops proxying requests for that buyer until they purchase again.

Authenticating ZeroClick#

Every request to your exchange endpoint carries two headers:

Your signing secret is shown in the dashboard under your service's settings. To verify a request:

1. Read the raw request body, before any JSON parsing or middleware touches it.
2. Compute HMAC-SHA256(signingSecret, "{timestamp}.{rawBody}") and hex-encode it.
3. Compare against the signature header using a constant-time comparison.
4. Reject requests whose timestamp is more than five minutes old to prevent replay.

import { createHmac, timingSafeEqual } from "node:crypto";
 
export function verifyZeroClickRequest(
	signingSecret: string,
	rawBody: string,
	timestampHeader: string,
	signatureHeader: string,
): boolean {
	const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestampHeader));
	if (!Number.isFinite(ageSeconds) || ageSeconds > 300) return false;
 
	const expected = `sha256=${createHmac("sha256", signingSecret)
		.update(`${timestampHeader}.${rawBody}`)
		.digest("hex")}`;
 
	const a = Buffer.from(signatureHeader);
	const b = Buffer.from(expected);
	return a.length === b.length && timingSafeEqual(a, b);
}

Retries and idempotency#

ZeroClick treats any 2xx response as success and retries other responses with exponential backoff. Make both operations idempotent:

• A repeated POST for the same userId and plan should return the same key, or a fresh key that replaces the old one. It should not create a duplicate buyer.
• A repeated DELETE for an already-revoked key should still return 200 OK.

If your endpoint is down during a purchase, ZeroClick keeps retrying and completes provisioning when it recovers; the buyer's proxied requests are held off until a key exists.