> ## 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.
</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.

## 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      |

## Related

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