Hostiva Development Manual: Domain Module 1.0¶

Version: 1.0
Last updated: 2026-02-27

1. Purpose¶

This manual defines the canonical integration contract between:

Hostiva Core (Domain services provider)
Airfree Cloud (SaaS reseller)

It is written to enable a working integration quickly, while still being rigorous enough for enterprise use (audits, support, QA, and long-term evolution).

2. Scope (v1.0)¶

✅ Included:

Sandbox-first domain lifecycle: Search → Order → Checkout
Tenant isolation via X-Tenant
Developer keys + permissions
Deterministic sandbox behaviors for testing
Default nameservers for DNS Cloud integration

⏳ Not in scope yet (future versions):

Transfers
Renewals
Contact handles
DNSSEC
Live registrar (Openprovider) production operations

3. Core Concepts¶

3.1 Environments¶

Sandbox - Safe and deterministic - Supports premium/taken/transfer/delay/failure simulations

Production - Real registrar integration (Openprovider planned) - Kill-switch protected

3.2 Tenant isolation¶

All requests must include:

X-Tenant: <tenant_slug> (e.g. airfree)
A matching developer key belonging to that tenant

3.3 Order state machine¶

stateDiagram-v2
  [*] --> created
  created --> pending_payment
  pending_payment --> paid
  paid --> provisioning
  provisioning --> completed
  provisioning --> failed
  failed --> [*]
  completed --> [*]

4. Quick Start (≤ 60 minutes)¶

If you want a fast demo for management, follow the Runbook page.
For full curl examples and onboarding checklist, use API Spec.

5. Canonical Contracts¶

This manual merges and normalizes the following sources into one standard:

Airfree ↔ Hostiva sandbox demo runbook
Domain API integration quickstart
Hostiva Integrations: Airfree Cloud Domain API (v1)

The original source documents are preserved in the repository history; the content below is the official v1.0 contract.

6. API, Webhooks, Test Matrix¶

Navigate to the next pages:

Architecture
API Spec
OpenAPI
Postman
Webhooks
Sandbox Matrix
Integration Flow
Runbook