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

# Domains

> Register and verify custom domains for your Grantex account via DNS TXT records.

## Overview

The `domains` client manages the registration and ownership-verification lifecycle for custom domains on your Grantex account. Register a domain, verify ownership via a DNS TXT record, list registered domains, and remove them.

<Note>
  Today the API covers registration, DNS verification, listing, and deletion. Runtime traffic routing — having Grantex consent UI and API endpoints actually served from your verified domain — is on the roadmap; both still resolve under `*.grantex.dev`.
</Note>

Access the domains client via `client.domains`.

## Create

Register a new custom domain. Returns a verification token that you must add as a DNS TXT record before calling `verify()`.

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    domain = client.domains.create("auth.example.com")

    print(f"ID: {domain.id}")
    print(f"Domain: {domain.domain}")
    print(f"Verified: {domain.verified}")
    print(f"Token: {domain.verification_token}")
    print(f"Instructions: {domain.instructions}")
```

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `domain` | `str` | Yes | The custom domain to register (e.g., `'auth.example.com'`). |

### DomainRegistration

| Field | Type | Description |
| - | - | - |
| `id` | `str` | Unique domain registration identifier. |
| `domain` | `str` | The registered domain name. |
| `verified` | `bool` | Whether the domain has been verified (initially `False`). |
| `verification_token` | `str` | The token value to add as a DNS TXT record. |
| `instructions` | `str` | Human-readable instructions for adding the DNS TXT record. |

## List

List all registered custom domains for the authenticated developer.

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    result = client.domains.list()

    for domain in result.domains:
        status = "verified" if domain.verified else "pending"
        print(f"{domain.domain} — {status}")
```

### ListDomainsResponse

| Field | Type | Description |
| - | - | - |
| `domains` | `list[DomainRegistration]` | List of registered domain objects. |

## Verify

Verify ownership of a registered domain by checking the DNS TXT record. Call this after adding the verification token to your DNS configuration.

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    result = client.domains.verify("dom_01HXYZ...")

    if result.verified:
        print("Domain verified successfully!")
    else:
        print("DNS record not found yet — try again after propagation.")
```

<Note>
  DNS propagation can take up to 48 hours. If verification fails, wait and try again. The verification token does not expire.
</Note>

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | `str` | Yes | The domain registration ID to verify. |

### DomainVerifyResponse

| Field | Type | Description |
| - | - | - |
| `verified` | `bool` | Whether the DNS TXT record was found and matches the verification token. |

## Delete

Remove a custom domain registration. The domain is immediately disassociated from your Grantex endpoints.

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    client.domains.delete("dom_01HXYZ...")
    # Returns None — domain registration is removed
```

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | `str` | Yes | The domain registration ID to delete. |

The method returns `None`. A `GrantexApiError` is raised if the domain does not exist.

## Example: Domain Setup Flow

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    # 1. Register a custom domain
    registration = client.domains.create("auth.myapp.com")
    print(f"Add this DNS TXT record:")
    print(f"  {registration.instructions}")
    print(f"  Value: {registration.verification_token}")

    # 2. After adding the DNS record, verify ownership
    verification = client.domains.verify(registration.id)
    if verification.verified:
        print("Domain verified successfully!")
    else:
        print("DNS record not found yet — try again after propagation.")

    # 3. List all domains
    result = client.domains.list()
    for d in result.domains:
        status = "verified" if d.verified else "pending"
        print(f"{d.domain} — {status}")

    # 4. Remove a domain when no longer needed
    client.domains.delete(registration.id)
```

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