Free and identity endpoints

Some endpoints cost nothing but still must know who is asking: polling a job the buyer created, reading account limits, any read or write served only to the buyer that owns the underlying records. Guarding them with guard would demand payment for free work; skipping the guard entirely would serve them to anyone. The identity guard is the middle path: it verifies the signature exactly like guard, requires a registered agent credential, and makes no allowance call. For shared setup and reference examples covering demo booking, lead capture, document delivery, and webinar registration, see Free actions.

Guard identity, not allowance

export async function GET(request: Request) {
  const decision = await zeroClick.guardIdentity(request, {
    serviceSlug: "product-watch",
  });
  if (decision.action === "deny") return decision.response;

  const jobId = new URL(request.url).pathname.split("/").pop();
  const job = await findJob(jobId, { owner: decision.context.zcAgentId });
  if (!job) return Response.json({ error: "not_found" }, { status: 404 });
  return Response.json(job);
}

@app.get("/v1/jobs/{job_id}")
async def job_status(request: Request, job_id: str) -> Response:
    zc_request = zc_request_from_asgi_scope(request.scope, await request.body())

    # Synchronous even on the async client: no network call, nothing to await.
    decision = zeroclick.guard_identity(zc_request, service_slug="product-watch")
    if decision.action == "deny":
        return to_fastapi(decision.response)

    return to_fastapi(
        ZcResponse.json({"jobId": job_id, "owner": decision.context.zc_agent_id})
    )

mux.Handle("/v1/limits", seller.Identify()(http.HandlerFunc(limits)))

func limits(w http.ResponseWriter, r *http.Request) {
	zc, _ := sellers.FromContext(r.Context())
	w.Header().Set("content-type", "application/json")
	json.NewEncoder(w).Encode(map[string]any{"zcAgentId": zc.AgentID})
}

The decision works like guard’s:

A failed signature is the usual 401 deny: unverified traffic never reaches free endpoints either.
A verified request with zc-agent-id allows, with allowance status not_required and the buyer in context. Scope your reads and writes to that id.
A verified request without a buyer, a signed anonymous probe, denies with reason identity_required and this exact body:

{ "error": "payment_required", "serviceSlug": "product-watch", "usage": [] }

The empty usage list tells ZeroClick the call costs nothing and needs an agent credential. ZeroClick answers with 401 bearer_required and a pointer to its registration recipe. The retry carries a pseudonymous zc-agent-id; the identity guard alone does not require a human claim or verified email. Configure the verified email policy separately when your workflow needs it. No payment is involved.

Identity and access are separate

A buyer that has registered holds an identity; billing needs an access grant on top of it. A purchase creates access, and allowance checks and usage reports draw against it (see agents and access). Reporting usage against an identity-only buyer fails with access_not_found. Keep the division clean: guardIdentity for free identity-scoped calls, guard for anything billable. The same division applies to settlement: no zc-usage belongs on a free response. There is nothing to settle. Free means free.

Included free units

There is a second kind of free: a plan’s meter price can grant includedUnits, an allowance of free units configured in your catalog (see plans and pricing). These are billable meters whose first units cost nothing, not identity-scoped endpoints, and they reach your API through the normal guard path:

The buyer opts in per call by sending zc-mode: free to the pay URL. ZeroClick operates paid-by-default: a missing or unrecognized mode means paid. The proxy consumes the header and never forwards it to you.
The free allowance needs no funding, but it does need a claimed agent. Free units are served only to an agent identity that a human has claimed with a verified email. An unclaimed agent, or one whose claim carries no verified email, gets no free units - its free-mode calls are refused like any unpaid call. A claim with a verified email, rather than a payment, is what stands between a new agent and its free units.
Free calls require an identified caller. Included-units coverage is per buyer - aggregated across every agent that human has claimed - so ZeroClick answers an unidentified free-mode call with 401 bearer_required and its registration-and-claim recipe. The identified retry re-runs the real coverage check, including the claimed-and-verified requirement.
Pay-as-you-go included units do not reset on a schedule. Consumption is tracked across the buyer’s agents for the service and meter, including deleted agents. Use your own counters for daily or monthly application quotas.
Your integration does not change. Guard the route and settle usage exactly as for paid traffic. For a covered free-mode call, the allowance check answers allowed, and the usage you settle draws down the buyer’s included allowance instead of charging.

For unmetered actions with application-enforced per-email limits, see reduce abuse of free actions. That symmetry is the point of the guard: paid, ceiling, included-free, and identity-only traffic all arrive as signed requests. The same four obligations (verify, check, serve, settle) handle every one. Back to the integration overview for the full contract, or on to settle usage if you came here mid-integration.

Get started

Concepts

Integrate your API

Your agent storefront

Agentify

Page views

Resources

Free and identity endpoints

Guard identity, not allowance

Identity and access are separate

Included free units

​Guard identity, not allowance

​Identity and access are separate

​Included free units

Guard identity, not allowance

Identity and access are separate

Included free units