---
title: "Discovery fields"
description: "The v1.2 agent-signup.json document field by field, including the optional provider verification credential, with types and rules."
image: "https://docs.agentregistrar.dev/og/docs-default.png"
---

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

# Discovery fields

A relying party publishes one identity-only document at `GET
/.well-known/agent-signup.json`. This page is a lookup table for that document.
The normative rules are in [the
specification](/agent-identity/v1/specification/#5-discovery-document-reference-identity-only);
this page does not replace them.

The machine-readable schema is served at
[`/agent-identity/v1/agent-signup.schema.json`](/agent-identity/v1/agent-signup.schema.json)
with content type `application/schema+json`. Validate a document with the
[conformance validator](/agent-identity/v1/validator/).

## Required fields

| Field | Type | Rule | Section |
| :--- | :--- | :--- | :--- |
| `protocol` | string | Exactly `"agent-identity-v1"`. Any other value means the service is unsupported; do not fall back. | [5.1](/agent-identity/v1/specification/#51-required-fields) |
| `audience` | string | Stable, case-sensitive service identifier with no whitespace. The agent places this exact value in the assertion `aud`; the relying party rejects a mismatch. | [5.1](/agent-identity/v1/specification/#51-required-fields) |
| `provider_name` | string | Human-readable service name. | [5.1](/agent-identity/v1/specification/#51-required-fields) |
| `issuer_allowlist` | array of strings | Non-empty, unique absolute issuer origins. No path, query, fragment or wildcard. Trailing slashes are normalized away. The broker `iss` must match one entry exactly. | [5.1](/agent-identity/v1/specification/#51-required-fields), [5.4](/agent-identity/v1/specification/#54-field-rules) |
| `required_scopes` | array of strings | Unique non-empty scopes. Brokered signup must include `tos:accept`. | [5.1](/agent-identity/v1/specification/#51-required-fields) |
| `terms.version` | string | ToS version. Change it whenever the text changes materially. | [5.1](/agent-identity/v1/specification/#51-required-fields), [6](/agent-identity/v1/specification/#6-tos-binding) |
| `terms.url` | string | Absolute URL where a human can read the same agreement. HTTPS is required except the documented localhost development exception. | [5.1](/agent-identity/v1/specification/#51-required-fields) |
| `terms.sha256` | string | `sha256:` followed by 64 lowercase hex characters, over the exact UTF-8 bytes of `terms.text`. | [5.1](/agent-identity/v1/specification/#51-required-fields), [6](/agent-identity/v1/specification/#6-tos-binding) |
| `terms.text` | string | The complete agreement the agent is accepting, not a summary. | [5.1](/agent-identity/v1/specification/#51-required-fields) |
| `endpoints.agent_signup` | string | Absolute URL that accepts `POST` with `Authorization: Bearer <assertion>`. The only endpoint in the protocol. | [5.1](/agent-identity/v1/specification/#51-required-fields) |

## Optional fields

| Field | Type | Rule | Section |
| :--- | :--- | :--- | :--- |
| `spec` | string | Absolute URL of the versioned specification. Optional; implementers may omit it. | [5.2](/agent-identity/v1/specification/#52-optional-fields) |
| `provider_url` | string | Canonical service URL. If present, it must share the signup endpoint's registrable domain. | [5.2](/agent-identity/v1/specification/#52-optional-fields), [11](/agent-identity/v1/specification/#11-contract-e-identity-facts--the-context-pointer) |
| `contact` | string | Security, abuse or legal contact: an email address or an HTTPS URL. The localhost development exception (`http://localhost`, `http://127.0.0.1`) is the only `http` form allowed. | [5.2](/agent-identity/v1/specification/#52-optional-fields) |
| `updated_at` | string | ISO 8601 timestamp for humans and debugging. Not a freshness signal for the ToS. | [5.2](/agent-identity/v1/specification/#52-optional-fields) |
| `rp_attestation` | string | Optional compact JWS, at most 16384 characters, issued by the provider's broker. It binds the fetched origin and the declared audience; absence means **unverified**, never invalid. A malformed field is a conformance error. | [5.2](/agent-identity/v1/specification/#52-optional-fields), [14](/agent-identity/v1/specification/#14-contract-g--rp-attestation) |
| `extensions` | object | Non-capability vendor metadata keyed by reverse-DNS namespace, for example `dev.example`. It must not advertise provisioning, catalogs, SKUs or resource endpoints. | [5.2](/agent-identity/v1/specification/#52-optional-fields), [5.3](/agent-identity/v1/specification/#53-forbidden-fields-vendor-capability-surface) |

Unknown additive fields must be ignored by consumers. Producers should put
non-capability metadata under `extensions.<reverse-dns-namespace>` so typos stay
visible. Moving a vendor capability under `extensions` does not make it
conformant.

## The optional provider verification credential

`rp_attestation` is the only discovery field that describes the provider's
broker-verified identity. It is a compact JWS (`typ:
agent-rp-attestation+jwt`, `alg: EdDSA`) whose claims bind `rp.origin`,
`rp.audience`, the provider identity, the assurance level, and the public
`keys[]`.

Rules:

- The attestation `rp.origin` must equal the canonical origin of the discovery
  document the verifier actually fetched.
- `rp.audience` must equal `discovery.audience`.
- The attestation is public and copyable; the origin and audience binding
  prevent replay on another service.
- It must not carry a terms hash, scopes, endpoints, `provider_url`, account ids,
  prices, or private material.
- A conformant document without it is **unverified**. An expired, invalid, or
  untrusted attestation is a verification result, never a conformance failure
  by itself. A malformed field is a conformance error.
- Do not add any other provider-identity or provider-capability field to
  discovery.

See [Trust and limits](/start/trust-and-limits/) and [Verify
assertions](/providers/guides/verify-assertions/) for the policy and verification
steps. If you are a provider and want the credential, see the [provider
quickstart](/providers/quickstart/).

## Forbidden fields

These must not appear at any nesting depth, including under `extensions`:

| Forbidden surface | Examples |
| :--- | :--- |
| Catalogs and commercial surface | `instance_catalog`, SKUs, pricing tiers, free-tier quotas, product specs |
| Provisioning and resource endpoints | `endpoints.provision`, resource endpoints, instance lifecycle |
| Legacy signup endpoints | `endpoints.email_signup`, `endpoints.verify_otp` |
| Broker receipt callback | `endpoints.broker_signup_receipt` |
| Credentials and API usage | resource credentials, vendor API or SDK usage metadata |

A document is a parameter document, not a capability catalog. Vendor capabilities belong in the post-signup context guide. See [Scope boundaries](/agent-identity/v1/scope-boundaries/) and the normative [5.3](/agent-identity/v1/specification/#53-forbidden-fields-vendor-capability-surface).

## Terms text and hash

- Hash the exact UTF-8 bytes of `terms.text`. Do not normalize line endings, trim whitespace or extract text from HTML.
- `terms.text` must be the complete agreement. A summary makes the hash ambiguous.
- The agent recomputes the hash before calling the broker; the broker verifies the accepted text against the hash it records.
- The relying party rejects an assertion whose `delegation.accepted_rp_tos_hash` is not the currently advertised `terms.sha256`.
- When the terms change, publish the new text and hash before accepting new signups. A bounded grace period for in-flight assertions is a relying-party policy documented outside discovery; it should not exceed 24 hours.

See [ToS binding](/agent-identity/v1/specification/#6-tos-binding) and [Re-acceptance](/agent-identity/v1/specification/#61-re-acceptance).

## Minimal conformant example

This document contains only the required identity fields. Its `terms.sha256` is
the real SHA-256 of the `terms.text` value shown. It passes the `v1.2.0`
validator in file mode with zero errors and zero warnings. The optional
`rp_attestation` is absent, so the document is conformant and **unverified**.

```json
{
  "protocol": "agent-identity-v1",
  "audience": "example-rp",
  "provider_name": "Example RP",
  "issuer_allowlist": ["https://agentregistrar.dev"],
  "required_scopes": ["tos:accept"],
  "terms": {
    "version": "2026.1",
    "url": "https://example.com/terms",
    "sha256": "sha256:05435fa3eaee7f3534b4a771ab2328d66d33f712f3534b29e9035717c246d953",
    "text": "Example RP Terms of Service. The agent acts for a verified human owner, and the human owner is bound by these terms."
  },
  "endpoints": {
    "agent_signup": "https://example.com/api/signup/agent"
  }
}
```

The example is illustrative. Replace the audience, URLs, scopes and terms with the service's own values, and recompute the hash. The allowlist entry is the live broker origin (`https://agentregistrar.dev`); a provider that accepts a different broker lists that broker's origin instead.

## Known limits

- The JSON Schema enforces the `sha256:` format, not digest equality. The digest check is a cross-field rule in the shared Zod schema and the conformance validator.
- Discovery conformance is cheap to publish. A valid document is not a statement about the service's security, uptime or product.
- The document itself is not signed in v1.2. The optional `rp_attestation` is a
  signed statement about the provider, not a signature over the discovery
  document. Trust in the document comes from TLS plus the issuer allowlist; the
  assertion and the attestation are separately signed.
- Consumers must ignore unknown additive fields, so a producer can add an identity field without a schema change. The validator warns on unknown top-level fields; warnings do not fail conformance.

## Verify

- Fetch the published document and confirm `Content-Type: application/json`.
- Recompute `terms.sha256` from the exact bytes of `terms.text`.
- Run the [validator](/agent-identity/v1/validator/) against the document.
- Confirm no forbidden field appears at any depth, including under `extensions`.

Source: https://docs.agentregistrar.dev/agent-identity/v1/discovery-fields/index.mdx