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

# Trust Registry

> Public organization directory with DID identity and DNS ownership verification.

## Overview

The Grantex Trust Registry is a public, searchable directory of organizations that publish AI agents. Organization records use DIDs as stable identifiers and can prove domain ownership through a DNS TXT challenge.

<Info>
  Search and organization-detail endpoints are public. Registration and DNS verification require a developer API key. The full listing of registry records, across developers, can be restricted to the service administrator credential, and operators should turn that on.
</Info>

<Warning>
  DNS ownership is the only self-service verification method implemented by the current public API. There is no public document-upload, SOC 2/ISO review, manual-review SLA, compliance-badge application, CDN badge widget, or automatic agent-linking workflow. Fields such as `badges`, `compliance`, and agent statistics may appear in responses, but their presence must not be treated as an independent certification unless an authoritative process is published.
</Warning>

## Public Search

```bash theme={null}
curl "https://api.grantex.dev/v1/registry/orgs?q=acme&verified=true&limit=20"
```

Supported filters are `q`, `verified`, `badge`, `category`, `limit`, and `cursor`. Results include an organization DID, name, description, verification level, stored badges, basic statistics, website, and logo URL when present.

```json theme={null}
{
  "data": [
    {
      "did": "did:web:acme.example",
      "name": "Acme AI",
      "verificationLevel": "verified",
      "badges": ["dns-verified"],
      "stats": {
        "totalAgents": 0,
        "weeklyActiveGrants": 0,
        "averageRating": 0
      }
    }
  ],
  "nextCursor": null
}
```

## Organization Detail

```bash theme={null}
curl "https://api.grantex.dev/v1/registry/orgs/did%3Aweb%3Aacme.example"
```

The detail response can include domain, public keys, stored compliance flags, contacts, verification method/time, and registered registry-agent records.

The organization's JWK Set is also public:

```bash theme={null}
curl "https://api.grantex.dev/v1/registry/orgs/did%3Aweb%3Aacme.example/jwks"
```

## Registration and Verification

Registration returns a one-time plaintext verification token and DNS instructions. The service stores only a hash afterward.

```bash theme={null}
curl -X POST https://api.grantex.dev/v1/registry/orgs \
  -H "Authorization: Bearer $GRANTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "did": "did:web:acme.example",
    "name": "Acme AI",
    "website": "https://acme.example",
    "contact": { "security": "security@acme.example" },
    "requestVerification": true,
    "verificationMethod": "dns-txt"
  }'
```

After publishing the returned token at `_grantex-verify.acme.example`, trigger verification with the returned `orgId` (the DID is also accepted by the API):

```bash theme={null}
curl -X POST "https://api.grantex.dev/v1/registry/orgs/$ORG_ID/verify-dns" \
  -H "Authorization: Bearer $GRANTEX_API_KEY"
```

Successful verification sets the organization to `verified`, records `dns-txt`, clears the stored token hash, and adds the `dns-verified` marker.

## Operator Listing

`GET /v1/trust-registry` returns the 100 newest registry records of every developer, verified or not. Because it crosses tenants, it is meant for the platform operator, but by default any developer API key can still read it, under that developer's plan budget.

Set `TRUST_REGISTRY_ADMIN_LISTING_ENFORCED=true` (read when the service starts) to restrict it. Operators should turn this on. With it on, the listing takes the service administrator credential (`ADMIN_API_KEY`, as `Authorization: Bearer <key>`), never a developer API key, and is limited to 20 calls a minute per address:

* A developer API key, a wrong key or no key is refused with `401 UNAUTHORIZED`, and nothing is read.
* While `ADMIN_API_KEY` is not configured, every call is refused with `503 SERVICE_UNAVAILABLE`.

Off, the default, and any value other than exactly `true`, keep the existing developer-API-key behaviour unchanged.

To look up one organization, use the public detail endpoints above.

## Endpoint Summary

| Method | Path | Authentication | Purpose |
| - | - | - | - |
| `GET` | `/v1/registry/orgs` | None | Search organizations |
| `GET` | `/v1/registry/orgs/:did` | None | Read organization detail |
| `GET` | `/v1/registry/orgs/:did/jwks` | None | Read organization public keys |
| `POST` | `/v1/registry/orgs` | Developer API key | Register an organization |
| `POST` | `/v1/registry/orgs/:orgId/verify-dns` | Developer API key | Verify its DNS challenge |
| `GET` | `/v1/trust-registry` | Developer API key; admin key (`ADMIN_API_KEY`) when `TRUST_REGISTRY_ADMIN_LISTING_ENFORCED=true` | List every developer's records (operator) |

## Accredited Issuers and Agent Attestations

The organization registry above is self-service, and its strongest check is DNS ownership. A separate layer of the registry lets accredited issuers vouch for agents:

* **Accredited issuers.** The registry operator accredits each issuer for specific trust-mark types, with a static JWKS and a `status_list_base`.
* **Attestations.** An issuer posts an attestation, a compact JWS, only for an agent key whose possession has been proven.
* **Trust levels.** The registry computes a level (`basic`, `verified`, `attested` or `attested_verified`) and flags, publishes its acceptance of each attestation on its own status lists, and fails closed: anything suspended reads `basic`.
* **Reads.** Relying parties read the result through the minimised agent lookup or the signed manifest `/.well-known/agent-registry.json`.
* **Passport-bound grants.** A grant can be bound to an Agent Passport, an SD-JWT VC from an accredited issuer, so it stops working when the registry no longer stands behind the passport.

Unauthenticated reads are behind `REGISTRY_PUBLIC_ENDPOINTS_ENABLED`, and passport-bound grants are behind `PASSPORT_BOUND_GRANTS_ENABLED`. Both are off by default; see [Self-Hosting](/self-hosting).

| Audience | Start here |
| - | - |
| Issuers | [Becoming an Accredited Issuer](/issuers/becoming-an-accredited-issuer), then [Running the Mock Issuer](/issuers/running-the-mock-issuer) |
| Providers | [Registering Agents](/providers/registering-agents) |
| Relying parties | [Verifying Agents](/relying-parties/verifying-agents) |
| Everyone | [Passport vs Grant](/concepts/passport-vs-grant) |

## Related

* [Trust Registry Setup](/guides/trust-registry-setup)
* [MPP Agent Passports](/features/mpp-agent-passport)
* [Security Best Practices](/guides/security-best-practices)

## Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in) or [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com).


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