Overview
The domains sub-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.
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.
const domain = await grantex.domains.create({ domain: 'auth.example.com' });
const verified = await grantex.domains.verify(domain.id);
const all = await grantex.domains.list();
await grantex.domains.delete(domain.id);
domains.create()
Register a new custom domain. Returns a verification token that you must add as a DNS TXT record before calling verify().
const domain = await grantex.domains.create({
domain: 'auth.example.com',
});
console.log(domain.id); // 'dom_01HXYZ...'
console.log(domain.domain); // 'auth.example.com'
console.log(domain.verified); // false
console.log(domain.verificationToken); // 'grantex-verify=abc123xyz...'
console.log(domain.instructions); // 'Add a TXT record to _grantex.auth.example.com ...'
Parameters
The custom domain to register (e.g., 'auth.example.com').
Response: DomainRegistration
Unique domain registration identifier.
The registered domain name.
Whether the domain has been verified (initially false).
The token value to add as a DNS TXT record.
Human-readable instructions for adding the DNS TXT record.
domains.list()
List all registered custom domains for the authenticated developer.
const result = await grantex.domains.list();
for (const domain of result.domains) {
console.log(domain.id); // 'dom_01HXYZ...'
console.log(domain.domain); // 'auth.example.com'
console.log(domain.verified); // true
}
Response: ListDomainsResponse
Array of registered domain objects.
domains.verify()
Verify ownership of a registered domain by checking the DNS TXT record. Call this after adding the verification token to your DNS configuration.
const result = await grantex.domains.verify('dom_01HXYZ...');
console.log(result.verified); // true
DNS propagation can take up to 48 hours. If verification fails, wait and try again. The verification token does not expire.
Parameters
The domain registration ID to verify.
Response: DomainVerifyResponse
Whether the DNS TXT record was found and matches the expected verification token.
domains.delete()
Remove a custom domain registration. The domain is immediately disassociated from your Grantex endpoints.
await grantex.domains.delete('dom_01HXYZ...');
// Returns void — domain registration is removed
Parameters
The domain registration ID to delete.
Response
Returns void. The domain registration is immediately removed.
Full example
import { Grantex } from '@grantex/sdk';
const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });
// 1. Register a custom domain
const registration = await grantex.domains.create({
domain: 'auth.myapp.com',
});
console.log(`Add this DNS TXT record:`);
console.log(` ${registration.instructions}`);
console.log(` Value: ${registration.verificationToken}`);
// 2. After adding the DNS record, verify ownership
const verification = await grantex.domains.verify(registration.id);
if (verification.verified) {
console.log('Domain verified successfully!');
} else {
console.log('DNS record not found yet — try again after propagation.');
}
// 3. List all domains
const { domains } = await grantex.domains.list();
for (const d of domains) {
console.log(`${d.domain} — ${d.verified ? 'verified' : 'pending'}`);
}
// 4. Remove a domain
await grantex.domains.delete(registration.id);
