> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroclick.ai/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, why anonymous probes exist, 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 signup, no buyer API keys, 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 …`. Buying an entitlement requires one: a plan purchase or top-up binds to the credential, so the buyer keeps its plan however it chooses to pay.

Pay-as-you-go callers need no credential and still get a `zcAgentId`: ZeroClick registers an anonymous agent for each payer. How stable that id is depends on the rail:

| Anonymous payer | What it gets                                                                                                                                  |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Crypto          | A durable id. The same payer returning over any network or protocol keeps the same `zcAgentId`, so it works as a foreign key across sessions. |
| Card            | A fresh id per payment. Treat these as single-transaction identifiers.                                                                        |

## 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](/concepts/usage-and-allowances), 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](/resources/headers) has the full matrix, including what the signature does and does not cover.

## Anonymous probes have no agent id

One forwarded request legitimately arrives without a buyer: the signed **anonymous probe**. When an unpaid pay-as-you-go request needs pricing, ZeroClick forwards it upstream 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](/concepts/how-zeroclick-works)). Nobody has paid yet, so there is no verified identity to attach: the probe carries no `zc-agent-id` header, and the signature's agent segment is the empty string. Identity binds at verify time, from the signed payment; only the paid retry carries the agent id:

```http Anonymous probe: valid signature, no agent theme={null}
zc-request-id: zcreq_8h2m4x0q9k1f
zc-signature: t=1785196800,kid=hsec_k5nq0v7m3d8p,v1=…
```

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

Both are valid, expected traffic. The [seller SDKs](/sdks/overview) and the [verification guide](/integrate/verify-requests) treat probes as a first-class case, so you rarely branch on them 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: first-contact buyers pay per call and go. The [plans and pricing](/concepts/plans-and-pricing) page covers what each billing mode means for these fields, and [usage and allowances](/concepts/usage-and-allowances) covers the checks that consume them.

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.
