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

> Register a did:web organization and complete DNS TXT ownership verification.

## Prerequisites

* A Grantex developer API key
* A domain you control
* Permission to publish a DNS TXT record

Use a `did:web` identifier matching the domain, for example `did:web:acme.example`.

## 1. Register the Organization

```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",
    "description": "Agent publisher",
    "website": "https://acme.example",
    "contact": {
      "security": "security@acme.example",
      "dpo": "dpo@acme.example"
    },
    "requestVerification": true,
    "verificationMethod": "dns-txt"
  }'
```

Save the complete response immediately:

```json theme={null}
{
  "orgId": "treg_01HXYZ...",
  "did": "did:web:acme.example",
  "name": "Acme AI",
  "trustLevel": "basic",
  "verificationToken": "grantex-verify-...",
  "instructions": "Add a DNS TXT record at _grantex-verify.acme.example with value ..."
}
```

<Warning>
  The verification token is returned only at registration time. Store it securely until verification completes; the service retains only its hash.
</Warning>

## 2. Publish the DNS Challenge

Create this record using the exact host and value returned in `instructions`:

| Setting | Value                            |
| ------- | -------------------------------- |
| Type    | `TXT`                            |
| Host    | `_grantex-verify.acme.example`   |
| Value   | The exact `verificationToken`    |
| TTL     | `300` or your provider's default |

Confirm the public record before calling the API:

```bash theme={null}
dig TXT _grantex-verify.acme.example
```

DNS propagation time is controlled by your provider and existing TTLs; no fixed completion time is guaranteed.

## 3. Trigger Verification

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

A successful response resembles:

```json theme={null}
{
  "orgId": "treg_01HXYZ...",
  "verified": true,
  "verificationMethod": "dns-txt",
  "trustLevel": "verified",
  "verifiedAt": "2026-07-10T12:00:00.000Z",
  "domain": "acme.example"
}
```

If the call returns `DNS_VERIFICATION_FAILED`, verify that the TXT value has no added quotes/spaces and query more than one public recursive resolver before retrying.

## 4. Confirm the Public Record

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

Check for `verificationLevel: "verified"`, `verificationMethod: "dns-txt"`, and the `dns-verified` marker.

## Portal Notes

The portal routes are `/dashboard/registry` and `/dashboard/registry/register`. Regardless of client, keep the one-time token returned by registration: it is required to create the DNS record.

## Current Limitations

The public API does not currently implement `.well-known` verification, report uploads, manual reviews, compliance-badge applications, public badge assets, or a trust-badge web component. Do not invent URLs or verification claims for those features.

## Related

* [Trust Registry reference](/features/trust-registry)
* [Registry integration summary](/integrations/registry)