How to use ECZ-ID badges safely

The one rule

A badge is a gateway. The proof lives in Resolver. Always click or scan the badge to confirm current state at the canonical Resolver host. Never rely on a screenshot, a cached image, a copied JSON snippet, or a marketplace listing as proof.

Roles at a glance

• Badge — a visible, clickable, scannable gateway that links to a Resolver page.
• Resolver — the only public proof surface. Canonical host: resolver.ecocitizenz.org.
• TrustOps — where the credential behind the badge is acquired and controlled.
• Developer Gateway — explains the model and routes you to the right surface. It does not host checkout and does not issue proof.

Safe rules for everyone displaying a badge

• Customer-bound badge must point to the customer Resolver page for that operator, agent, or API surface.
• Family or template badges are general explainers. They are not customer proof and must not be presented as such.
• The badge target URL must use the canonical Resolver host: https://resolver.ecocitizenz.org.
• Do not embed a static badge image without an active link or scannable code that resolves to Resolver.
• Do not crop, recolour, or alter the badge so that the link or scannable element is removed.
• Do not claim certification, approval, partnership, guarantee, or marketplace endorsement on or near the badge.
• Do not say the badge proves safety, security, or compliance. The badge points at proof; Resolver shows current state.

Safe rules for customers and end users

• Treat any badge image without a working link to resolver.ecocitizenz.org as unverified.
• Click the badge or scan its code, then confirm the host bar shows resolver.ecocitizenz.org.
• Confirm the Resolver page identifies the operator, agent credential, or API passport you expected.
• If the Resolver page shows revoked, suspended, mismatch, or stale, do not treat the badge as current.
• Screenshots, PDFs, and recordings of past Resolver pages are not current proof.

Safe rules for developers and platforms

• Render the badge as an anchor whose href is the customer Resolver page on resolver.ecocitizenz.org.
• Set rel="noopener" on external badge links. Do not strip rel attributes when copying examples.
• Do not proxy, mirror, or rehost the Resolver page. Always link out to the canonical host.
• Surface the resolver_url and any api_passport_id from the operator manifest. Do not invent values.
• Fail closed if the manifest cannot be discovered or the Resolver URL does not resolve to the expected operator.
• Do not display the badge alongside copy that overclaims certification or approval.

Safe rules for procurement teams

• In supplier files, store the supplier Resolver URL, not a screenshot of the badge.
• Re-check the Resolver URL at each contract milestone. Treat lifecycle states such as suspended, revoked, or stale as material.
• A family or template badge in a brochure is marketing, not customer proof. Ask for the customer-bound Resolver URL.
• Record the operator_ecz_id and api_passport_id where applicable, plus the date of last verification.

Safe rules for agents and automated systems

• Resolve the badge target by following the manifest resolver_url, not by parsing the rendered image.
• Verify the host is resolver.ecocitizenz.org over HTTPS before trusting the response.
• Cache for short windows only. Always re-check Resolver before high-impact actions.
• Do not present a cached Resolver response to downstream consumers as current proof.

Safe HTML embed

<a
  href="https://resolver.ecocitizenz.org/p/ECZ-GB-EXAMPL/AGENT/ABC123"
  target="_blank"
  rel="noopener"
  aria-label="Verify this ECZ-ID Agent Credential in Resolver"
>
  <img
    src="https://resolver.ecocitizenz.org/badge/ECZ-GB-EXAMPL/AGENT/ABC123.svg"
    alt="ECZ-ID — verify in Resolver"
    width="180" height="32"
  />
</a>

Safe Markdown embed

[![ECZ-ID — verify in Resolver](https://resolver.ecocitizenz.org/badge/ECZ-GB-EXAMPL/API/DEF456.svg)](https://resolver.ecocitizenz.org/p/ECZ-GB-EXAMPL/API/DEF456)

Safe procurement note

Supplier ECZ-ID reference
-------------------------
Operator ECZ-ID:    ECZ-GB-EXAMPL
Agent Credential:   ECZ-GB-EXAMPL::AGENT-ABC123
API Passport:       ECZ-GB-EXAMPL::API-DEF456
Resolver URL:       https://resolver.ecocitizenz.org/p/ECZ-GB-EXAMPL/AGENT/ABC123
Verified on:        YYYY-MM-DD by <reviewer>
Note: badge images are gateways. Current state must be re-checked in Resolver
at the URL above. Family or template badges are not customer proof.

Safe OpenAPI / agent metadata reference

openapi: 3.1.0
info:
  title: Example Support API
  version: "1.0.0"
  x-ecz-id:
    operator_ecz_id: ECZ-GB-EXAMPL
    api_passport_id: ECZ-GB-EXAMPL::API-DEF456
    manifest_url: https://example.com/.well-known/ecz-agent.json
    resolver_url: https://resolver.ecocitizenz.org/p/ECZ-GB-EXAMPL/API/DEF456
    badge_use: gateway-only
  x-ecz-api-passport: ECZ-GB-EXAMPL::API-DEF456

Safe ecz-agent.json reference for agents

{
  "schema_version": "ecz-agent-json-v1",
  "operator_ecz_id": "ECZ-GB-EXAMPL",
  "agent_credential_id": "ECZ-GB-EXAMPL::AGENT-ABC123",
  "manifest_url": "https://example.com/.well-known/ecz-agent.json",
  "resolver_url": "https://resolver.ecocitizenz.org/p/ECZ-GB-EXAMPL/AGENT/ABC123",
  "badge_use": "gateway-only"
}

Need an ECZ-ID? Where to learn next

• Agent Trust hub — model, surfaces, and discovery: /agent-trust
• Manifest & discovery surfaces: /agent-trust/manifest
• ECZ-ID Agent Credential setup (ecz-agent.json): /agent-trust/ecz-agent-json
• ECZ-ID API Passport overview: /agent-trust/api-passport
• OpenAPI x-ecz-id reference: /agent-trust/openapi-x-ecz-id
• Guided Agent Trust flow: /flows/agent-trust
• Vendor procurement flow: /flows/vendor-procurement
• Developer onboarding: /developer-onboarding

What this page does not do

• It does not issue badges or credentials.
• It does not host checkout. Acquisition routes to TrustOps.
• It does not host or replace Resolver. Current proof lives at resolver.ecocitizenz.org.
• It does not certify, approve, or guarantee any operator, agent, or API.