> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents and access

> How ZeroClick identifies buying agents, what zcAgentId and zcBuyerId mean to sellers, which forwards carry no agent id, and how access grants work.

An agent's identity on ZeroClick is a credential it registers for. Sellers see one opaque, stable id per buyer and handle nothing else: no buyer accounts or API keys to issue, no payment details.

## Identity is a registered credential

An agent registers once and exchanges an assertion for an access token, then presents that token as `Authorization: Bearer …` (or `ZC-Agent-Authorization: Bearer …` when `Authorization` already carries an MPP payment credential). Every call needs a registered agent credential, sent as a bearer: registering is one free API call, with no human step. An agent can register anonymously, sign in with its user's Zero identity, or be claimed by a human with a verified email. A call without a credential gets `401 bearer_required` before it reaches your API.

Pay-as-you-go is no exception, and a plan purchase or top-up binds to the credential, so the buyer keeps its plan however it chooses to pay. The `zcAgentId` on every call is the agent behind the bearer, so it stays the same across calls, sessions, and payment rails, card included.

## What sellers see: `zcAgentId`

Sellers only ever see a buyer as `zcAgentId`, an id shaped like `agt_x7f2kq93bh0d`. It is stable per buyer and appears consistently across the product: the `zc-agent-id` request header on forwarded requests, the `zcAgentId` field in 402 challenge bodies, [usage reports and usage events](/docs/concepts/usage-and-allowances.md), and transaction analytics. Use it as your foreign key for per-buyer state: rate limits, tenancy, audit logs.

## Agents belong to buyers: `zcBuyerId`

An agent is one credential. A **buyer** is the person or company behind it, and one buyer can hold several agents: a replacement for a rotated credential, a second agent for a different workload, a recovered identity from an earlier registration. Entitlements live on the buyer, so every agent a buyer holds can draw on every plan the buyer bought, no matter which agent made the purchase.

When ZeroClick knows the owner, forwarded requests carry `zc-buyer-id` (`byr_3n8v1c6t5j2w`) alongside `zc-agent-id`:

```http Agent whose owner is known theme={null}
zc-request-id: zcreq_8h2m4x0q9k1f
zc-agent-id: agt_x7f2kq93bh0d
zc-buyer-id: byr_3n8v1c6t5j2w
zc-signature: t=1785196800,kid=hsec_k5nq0v7m3d8p,v1=…
```

`zc-agent-id` is always the agent that made **this** call. It never switches to the agent that originally bought the plan being drawn down, so a request from a buyer's second agent looks like exactly what it is. The buyer id is what stays stable across all of them.

No `zc-buyer-id` means an anonymous agent: identified, billable, and fine to serve, but not yet attached to an owner you should key durable records to. Prefer `zc-buyer-id` for anything a human should still see after the agent that created it is gone, and `zc-agent-id` for per-caller concerns like rate limits. The [headers reference](/docs/resources/headers.md) has the full matrix, including what the signature does and does not cover.

## Agent ids on unpaid and paid calls

Every buyer call arrives with its agent id, including the unpaid one. When a pay-as-you-go request needs pricing, ZeroClick forwards it upstream with the caller's `zc-agent-id` so your API can state its price as a `402 payment_required` refusal. ZeroClick re-prices that refusal into the buyer's challenge (see [how ZeroClick works](/docs/concepts/how-zeroclick-works.md)), and the paid retry carries the same request id and the same agent:

```http Unpaid call: priced by your 402 refusal theme={null}
zc-request-id: zcreq_8h2m4x0q9k1f
zc-agent-id: agt_x7f2kq93bh0d
zc-signature: t=1785196800,kid=hsec_k5nq0v7m3d8p,v1=…
```

```http Paid retry: same request id, same agent theme={null}
zc-request-id: zcreq_8h2m4x0q9k1f
zc-agent-id: agt_x7f2kq93bh0d
zc-signature: t=1785196819,kid=hsec_k5nq0v7m3d8p,v1=…
```

A signed request with no `zc-agent-id` is still valid: ZeroClick probes your endpoints that way when it builds your catalog, and the signature's agent segment is then the empty string. The [seller SDKs](/docs/sdks/overview.md) and the [verification guide](/docs/integrate/verify-requests.md) treat it as a first-class case, so you rarely branch on it yourself.

## Access grants

A purchase creates a buyer **access**: the grant that ties one buyer to one plan at one seller, and the thing every allowance check evaluates. Each buyer holds at most one active access per seller. Buying again or switching plans replaces the grant in place rather than stacking a second one. Any remaining credit carries forward onto the new purchase, so an unspent balance survives a plan switch.

An access carries:

* `status`: `active` or `inactive`. Checks against an inactive access are denied `access_inactive`.
* `periodStartsAt` / `periodEndsAt`: the current period for subscription-style plans. A check after `periodEndsAt` is denied `plan_expired`.
* `remainingCreditUsd`: the prepaid balance on credit plans, or the included usage credit on `subscription_usage` plans. Usage draws it down; an amount it cannot cover is denied `usage_exhausted`.

Pay-as-you-go needs no access at all: a registered agent pays per call and goes. The [plans and pricing](/docs/concepts/plans-and-pricing.md) page covers what each billing mode means for these fields, and [usage and allowances](/docs/concepts/usage-and-allowances.md) covers the checks that consume them.

For most sellers the access grant is the whole story of a purchase. A seller can also opt into something more: the purchase creates a real account on the seller's side, with a durable `accessId` handle and an API key the buyer then uses with the seller directly — see [sell accounts and API keys](/docs/integrate/stateful-sellers.md).

Identity stays verified per call. Even on a purchased plan, every request carries the buyer's credential, and ZeroClick resolves it to the same `agt_…` before it forwards, so your API needs no buyer authentication of its own. The `zc-signature` header is the trust boundary.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.