Domains

The Domains API lets you buy and manage domain names through your operator's registrar account, paying from your Lahijan balance. It covers four actions: check availability, register, renew and transfer in. Hosting the DNS for a domain is a separate step, done with Zones.

All examples use your access token and tenant ID, as described in the DNS overview.

Domain name format

Send domain names without a trailing dot, in lowercase, with no spaces: example.com, not example.com. or Example.com. Otherwise the request fails with 400 bad_request. Responses show stored names with a trailing dot (example.com.).

Check availability

POST /api/v1/dns/domains/search

curl -X POST https://app.example.com/api/v1/dns/domains/search \  -H "Authorization: Bearer $LAHIJAN_TOKEN" \  -H "X-Tenant-Id: $TENANT_ID" \  -H "Content-Type: application/json" \  -d '{"domain": "example.com"}'

Example response:

{	"domain": "example.com",	"available": true,	"status": "available",	"pricing": [		{ "periodYears": 1, "priceCents": 1500, "currency": "USD" },		{ "periodYears": 2, "priceCents": 3000, "currency": "USD" }	]}

• status is available or unavailable. reason may explain why a name is unavailable.
• pricing lists the price for each registration period the registrar offers, in integer cents. Prices already include any margin your operator adds.

Each search is recorded in the audit log, because registrars may bill the operator per lookup. Searching needs dns.domain.search, which every default role has.

Register a domain

POST /api/v1/dns/domains

curl -X POST https://app.example.com/api/v1/dns/domains \  -H "Authorization: Bearer $LAHIJAN_TOKEN" \  -H "X-Tenant-Id: $TENANT_ID" \  -H "Content-Type: application/json" \  -d '{    "domain": "example.com",    "periodYears": 1,    "autoRenew": false,    "whoisPrivacy": true,    "contact": {      "ownerFirstname": "Sara",      "ownerLastname": "Ahmadi",      "ownerOrganization": "Example Ltd",      "ownerEmail": "sara@example.org",      "ownerPhone": "+982112345678",      "address1": "1 Main Street",      "city": "Tehran",      "state": "Tehran",      "zip": "1234567890",      "countryCode": "IR"    }  }'

What happens:

1. Lahijan checks availability again. If the name is taken, you get 409 conflict. If the registrar has no price for the requested period, you get 400 bad_request.
2. The price for that period is charged to your balance as a ledger entry. Lahijan does not check that your balance covers the charge first.
3. The order is placed with the registrar. If the registrar rejects it, Lahijan adds a refund entry that reverses the charge.
4. On success you get 201 with the domain record.

After registering, create a zone for the domain (see Zones) and make sure the domain's nameservers point to your operator's nameservers (see How delegation works).

The domain record

Each registered, renewed or transferred domain appears in your tenant's list:

List and view them with:

• GET /api/v1/dns/domains (paginated with limit and offset)
• GET /api/v1/dns/domains/{domainId}

These need dns.domain.read.

Renew a domain

POST /api/v1/dns/domains/{domainId}/renew

curl -X POST https://app.example.com/api/v1/dns/domains/$DOMAIN_ID/renew \  -H "Authorization: Bearer $LAHIJAN_TOKEN" \  -H "X-Tenant-Id: $TENANT_ID" \  -H "Content-Type: application/json" \  -d '{"periodYears": 1}'

periodYears is 1 to 10. The price is worked out from the per-year price stored when the domain was registered. The charge is posted first and reversed with a refund entry if the registrar refuses the renewal. The response (200) is the domain record with the new expiresAt.

Transfer a domain in

POST /api/v1/dns/domains/transfer

curl -X POST https://app.example.com/api/v1/dns/domains/transfer \  -H "Authorization: Bearer $LAHIJAN_TOKEN" \  -H "X-Tenant-Id: $TENANT_ID" \  -H "Content-Type: application/json" \  -d '{"domain": "example.com", "authCode": "Xy7-auth-code", "periodYears": 1}'

Before you start, remove the transfer lock at your current registrar. If the registrar refuses the transfer (for example because the domain is still locked or the code is wrong), the request fails and the charge is refunded.

Transfers are charged a fixed 10.00 per year in the platform's billing currency, plus any operator margin. The response is 201 with the domain record; its status is usually pending until the transfer completes.

Remove a domain from the list

DELETE /api/v1/dns/domains/{domainId} returns 204.

This only removes the domain from your tenant's list in Lahijan. It does not cancel the registration or stop auto-renewal at the registrar, and nothing is refunded. It needs dns.domain.delete, which the default Tenant member role does not have.

Errors

Charges and refunds appear in your ledger. See Balance and usage.