Domains API

Register custom email domains so identities receive mail at addresses like agent@yourdomain.com instead of the default @inbox.aidenid.com.

DNS setup

To use a custom domain, you need to add two DNS records at your domain registrar:

The exact TXT verification value is returned when you register the domain. DNS propagation typically takes 5 to 30 minutes.

Register a domain

Register a custom domain for use with identity email addresses. Returns the DNS records you need to configure.

Request body

curl

curl -X POST https://api.aidenid.com/v1/domains \
  -H "Authorization: Bearer aid_your_api_key" \
  -H "X-Org-Id: org_abc123" \
  -H "X-Project-Id: proj_def456" \
  -H "Idempotency-Key: <GENERATED_UNIQUE_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "mail.yourdomain.com" }'

Python

import requests

resp = requests.post(
    "https://api.aidenid.com/v1/domains",
    headers={
        "Authorization": "Bearer aid_your_api_key",
        "X-Org-Id": "org_abc123",
        "X-Project-Id": "proj_def456",
        "Idempotency-Key": "domain-register-001",
    },
    json={"domain": "mail.yourdomain.com"},
)
domain = resp.json()
print("Add these DNS records:")
for record in domain["dns_records"]:
    print(f"  {record['type']} {record['host']} -> {record['value']}")

Response 201 Created

{
  "id": "dom_k1l2m3n4",
  "domain": "mail.yourdomain.com",
  "status": "pending_verification",
  "dns_records": [
    {
      "type": "MX",
      "host": "mail.yourdomain.com",
      "value": "10 mx.aidenid.com",
      "status": "pending"
    },
    {
      "type": "TXT",
      "host": "_aidenid-verify.mail.yourdomain.com",
      "value": "aidenid-verify=dom_k1l2m3n4_v9w8x7",
      "status": "pending"
    }
  ],
  "created_at": "2026-04-06T10:00:00Z"
}

List domains

List all registered domains for the current project, including their verification status.

curl

curl "https://api.aidenid.com/v1/domains" \
  -H "Authorization: Bearer aid_your_api_key" \
  -H "X-Org-Id: org_abc123" \
  -H "X-Project-Id: proj_def456"

Response 200 OK

{
  "items": [
    {
      "id": "dom_k1l2m3n4",
      "domain": "mail.yourdomain.com",
      "status": "verified",
      "created_at": "2026-04-06T10:00:00Z",
      "verified_at": "2026-04-06T10:15:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Get domain details

Retrieve a specific domain, including the full DNS records required for verification.

curl

curl "https://api.aidenid.com/v1/domains/dom_k1l2m3n4" \
  -H "Authorization: Bearer aid_your_api_key" \
  -H "X-Org-Id: org_abc123" \
  -H "X-Project-Id: proj_def456"

Verify domain

Trigger a DNS verification check for the domain. AIdenID will look up the required MX and TXT records and update the domain status.

curl

curl -X POST https://api.aidenid.com/v1/domains/dom_k1l2m3n4/verify \
  -H "Authorization: Bearer aid_your_api_key" \
  -H "X-Org-Id: org_abc123" \
  -H "X-Project-Id: proj_def456" \
  -H "Idempotency-Key: <GENERATED_UNIQUE_KEY>"

TypeScript

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 10_000);
const res = await fetch(
  "https://api.aidenid.com/v1/domains/dom_k1l2m3n4/verify",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer aid_your_api_key",
      "X-Org-Id": "org_abc123",
      "X-Project-Id": "proj_def456",
      "Idempotency-Key": "verify-001",
    },
    signal: controller.signal,
  }
);
clearTimeout(timeout);
const result = await res.json();
console.log("Verification status:", result.status);

Response 200 OK

{
  "id": "dom_k1l2m3n4",
  "domain": "mail.yourdomain.com",
  "status": "verified",
  "dns_records": [
    { "type": "MX", "host": "mail.yourdomain.com", "value": "10 mx.aidenid.com", "status": "verified" },
    { "type": "TXT", "host": "_aidenid-verify.mail.yourdomain.com", "value": "aidenid-verify=dom_k1l2m3n4_v9w8x7", "status": "verified" }
  ],
  "verified_at": "2026-04-06T10:15:00Z"
}

Remove domain

Remove a registered domain. Active identities using this domain will continue to receive mail until they expire — no new identities can be created on the domain after removal.

curl

curl -X DELETE https://api.aidenid.com/v1/domains/dom_k1l2m3n4 \
  -H "Authorization: Bearer aid_your_api_key" \
  -H "X-Org-Id: org_abc123" \
  -H "X-Project-Id: proj_def456" \
  -H "Idempotency-Key: <GENERATED_UNIQUE_KEY>"

Response 204 No Content

Error codes

Related

• Identities API — use custom domains when creating identities
• Authentication — required headers for API requests
• Billing API — domain limits vary by plan