---
title: "Validate and register"
description: "Run the v1.2 conformance and attestation validator, read its verdicts and exit codes, and submit registry evidence."
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.

# Validate and register

**Goal:** prove the discovery document conforms, optionally prove the provider
verification credential verifies, then get the implementation listed with
reproducible evidence.

Conformance and verification are **two independent results**. The validator
reference is [Conformance validator](/agent-identity/v1/validator/). The registry
criteria and entry schema are in the [implementation
registry](https://github.com/agentregistrar/spec/blob/main/registry/README.md).
This page is the `/registry` target; there is no separate registry page.

## Run the validator

From a clone of the spec repository:

```bash
git clone https://github.com/agentregistrar/spec
cd spec
pnpm install
pnpm --silent validate:discovery https://example.com/.well-known/agent-signup.json --json
```

From any project, using the published package. There is no `bin` entry, so
invoke the TypeScript source with `tsx`:

```bash
npm install @agentregistrar/discovery@1.2.0 tsx@4.23.15
npx tsx node_modules/@agentregistrar/discovery/src/validate-discovery.ts \
  https://example.com/.well-known/agent-signup.json --json
```

File mode needs no network:

```bash
pnpm --silent validate:discovery ./agent-signup.json --json
```

Use `pnpm --silent` (or `pnpm -s`) so pnpm's banner does not pollute stdout. The
validator itself writes only JSON.

## Flags added in v1.2

| Flag | Effect |
| :--- | :--- |
| `--verify-attestation` | Parse and verify `rp_attestation` if present. Opt-in issuer JWKS fetch; an absent field is `unverified` plus a warning and does not change the exit code. |
| `--require-attestation` | Implies `--verify-attestation`; any non-`verified` result fails the run. Use it as a CI gate. |
| `--trusted-rp-broker <issuer>` | Repeatable trusted RP-broker list. Flags override the `AGENT_IDENTITY_TRUSTED_RP_BROKERS` env fallback; an empty effective list trusts nothing. |
| `--jwks <path-or-url>` | Pin exactly one issuer's JWKS for an offline run. It never bypasses signature checks and never merges issuers. |
| `--at <rfc3339\|epoch>` | Freeze the clock for deterministic fixture runs. Not for production. |

The existing `--json`, `--probe-jwks`, `--probe-endpoints`, `--timeout`, and
`--max-bytes` flags keep their meanings.

## Two verdicts and exit codes

The JSON result has `conformance` (document-only) and `attestation` (separate).
`valid` remains the run result: `valid === (exitCode === 0)`.

| Exit | Meaning | Next action |
| :--- | :--- | :--- |
| `0` | The document was fetched, parsed, and is conformant; no required check failed. Warnings do not change the code. | Publish. Verification may still be `unverified`, `expired`, or `invalid` without `--require-attestation`. |
| `1` | A conformance error (including unparseable JSON or a malformed `rp_attestation` field), or a failed attestation under `--require-attestation`. | Read the `errors` array and fix the document or the credential. |
| `2` | The run could not obtain what it needed: document read/fetch failure, or JWKS unavailable under `--require-attestation`. The conformance verdict is not evaluated. | Fix hosting, the URL, the timeout, or the JWKS, then re-run. |

A malformed `rp_attestation` field is a **conformance** error with
`attestation.status: "not_checked"`, not `invalid`. An expired attestation is a
verification warning by default. A bad signature, origin mismatch, or audience
mismatch is a verification failure. An absent credential is `unverified`.

## Recorded v1.2 runs

The v1.2.0 release notes record the fixture matrix and validator output. The
headline cases:

| Case | Command shape | Result |
| :--- | :--- | :--- |
| Conformant, no credential | `validate:discovery fixtures/valid-minimal.json --json` | `valid true`, exit `0`, `attestation.status "unverified"`. |
| Valid `domain` credential | `--verify-attestation --require-attestation --trusted-rp-broker ... --at ...` | `verified`, level `domain`, exit `0`. |
| Expired credential, advisory | `--verify-attestation --at <after exp>` | `expired`, exit `0`. |
| Expired credential, gate | same plus `--require-attestation` | exit `1`. |
| Malformed field | no flags needed | conformance error, exit `1`, `not_checked`. |
| Untrusted broker | `--verify-attestation` without trust | `attested_untrusted_broker`; exit `0` unless required. |
| Broker unavailable | `--require-attestation` with a missing JWKS | exit `2`, `unavailable`. |

Run `pnpm validate:fixtures` and `pnpm validate:registry` for the full matrix
and the registry schema.

## Validate a live provider

```bash
pnpm --silent validate:discovery https://example.com/.well-known/agent-signup.json \
  --verify-attestation \
  --trusted-rp-broker https://agentregistrar.dev \
  --json
```

Add `--require-attestation` for a gate. Do not add a trusted broker you have not
decided to trust: the check happens before any JWKS fetch, and the validator
never contacts an untrusted issuer.

## Registry criteria

To be listed, an implementation must:

1. Pass the identity-only validator with zero errors. Warnings are permitted.
2. Publish a public, stable HTTPS `/.well-known/agent-signup.json` on its
   canonical origin, not a per-deploy or throwaway URL.
3. Provide a reachable security, abuse or legal contact that someone monitors.
4. Publish a post-signup context guide if it has vendor capabilities to document.
5. **Optionally**, carry a five-field `verification` snapshot if it claims
   verification.

The registry lists protocol capabilities only: `agent_signup` and
`post_signup_context`. A catalog, a SKU or a provisioning endpoint is not a
registry capability. Listing is a statement about the discovery document, not an
endorsement of the product, its security, its uptime or its pricing.

## The optional verification snapshot

Verification is a separate statement from conformance. To claim it, the entry
carries all five fields:

```json
"verification": {
  "broker": "https://agentregistrar.dev",
  "level": "domain",
  "attestation_jti": "rpa_01j...",
  "checked_at": "2026-10-24T00:00:00Z",
  "status": "active"
}
```

- `level` is `domain` or `entity`.
- `status` is `active`, `suspended`, or `revoked` **at `checked_at`**.
- The attestation must be live at `checked_at`, and `checked_at` must fall inside
  its lifetime.
- The provider must have a real provider account with the attesting broker.

The registry is a **snapshot**, not a live feed. A later suspension or revocation
does not rewrite the static entry or badge until a new check is recorded.
Only `status:"active"` at `checked_at` renders the verified badge. The badge is
separate from the conformance badge; there is no second verified badge.

A provider account is required only for this verified listing, attestation
issuance, authenticated receipts, and abuse standing. It is not required to
accept assertions, and there is no pricing or checkout in this release.

## Submit an entry

1. Make the document conformant using [Publish discovery](/providers/guides/publish-discovery/).
2. Run the validator against the public URL and keep the JSON.
3. Open a pull request against `agentregistrar/spec` that adds one object to the
   `implementations` array in `registry/implementations.json` with:
   - `name`, `url`, `discovery_url`, `audience`, `protocol`, `capabilities`,
     `contact`, `validated_at`, `validator_version`;
   - a `validator_evidence` object with the exact command and resulting counts;
   - optionally, the five-field `verification` object above.
4. Update the table in `registry/README.md` so it stays in lockstep.
5. Run `pnpm --silent validate:registry registry/implementations.json --json`;
   it must report `valid: true`, exit `0`.
6. The pull request is reviewed against the criteria above.

Read `audience` and `protocol` from the validator's `--json` output rather than
retyping them. The field reference is in the [validator
guide](/agent-identity/v1/validator/).

An entry whose document stops passing is removed or updated with fresh evidence.

## Verify your work

- [ ] The file-mode run exits `0` with zero errors.
- [ ] The live URL run exits `0` and the content type is `application/json`.
- [ ] `--verify-attestation` is `verified` if and only if the credential is present and you trust the broker.
- [ ] `--require-attestation` fails closed on absent, invalid, expired, untrusted, or unavailable.
- [ ] The registry object contains no vendor capability fields.
- [ ] Any `verification` object has all five fields, a live `checked_at`, and only an `active` snapshot gets a badge.
- [ ] The table and the JSON stay in lockstep.

## Next

- [Production checklist](/providers/guides/production-checklist/): what to do before and after listing.
- [Troubleshooting](/providers/troubleshooting/): common validator failures.
- [Reference implementation](/providers/reference-vaporcloud/): the reference document and its evidence.
- [Trust and limits](/start/trust-and-limits/): policy, unverified providers, and what verification does not mean.

Source: https://docs.agentregistrar.dev/providers/guides/validate-and-register/index.mdx