Skip to main content

​
Endpoint

POST /v1/domains

​
Authentication

Requires a developer API key in the Authorization header.

​
Request Headers

HeaderValue
AuthorizationBearer <api_key>
Content-Typeapplication/json

​
Request Body

FieldTypeRequiredDescription
domainstringYesThe custom domain to register (e.g. auth.example.com)

​
Example Request

curl -X POST https://grantex-auth-dd4mtrt2gq-uc.a.run.app/v1/domains \
  -H "Authorization: Bearer gx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "auth.example.com"
  }'

​
Response — 201 Created

{
  "id": "dom_01HXYZ...",
  "domain": "auth.example.com",
  "verified": false,
  "verificationToken": "grantex-verify-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "instructions": "Add a DNS TXT record: _grantex.auth.example.com = grantex-verify-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

​
Response Fields

FieldTypeDescription
idstringUnique domain ID
domainstringThe registered domain
verifiedbooleanWhether the domain has been verified (always false on creation)
verificationTokenstringToken to add as a DNS TXT record for verification
instructionsstringHuman-readable DNS configuration instructions

​
Error Responses

StatusCodeDescription
400BAD_REQUESTMissing domain field
401UNAUTHORIZEDInvalid or missing API key
402PLAN_LIMIT_EXCEEDEDCustom domains require Enterprise plan
409CONFLICTDomain already registered

​
SDK Examples

import Grantex from '@grantex/sdk';

const grantex = new Grantex({ apiKey: 'gx_...' });

const domain = await grantex.domains.create({ domain: 'auth.example.com' });
console.log(domain.verificationToken);
console.log(domain.instructions);