API Specification (v1.0)¶

Base URL (Sandbox): https://core.hostiva.quantumdevlabs.com/api/v1

1. Required headers¶

Authorization: Bearer <DEVKEY>
X-Tenant: <tenant_slug>
Accept: application/json
Content-Type: application/json

Recommended: - X-Idempotency-Key: <uuid>

2. Response conventions¶

Success:

{
  "success": true,
  "data": {},
  "error": null,
  "meta": {
    "source": "hostiva-sandbox",
    "environment": "sandbox"
  }
}

Failure:

{
  "success": false,
  "data": null,
  "error": {
    "code": "DOMAIN_TAKEN",
    "message": "Domain is already registered."
  }
}

3. Endpoints (Sandbox)¶

3.1 Search¶

POST /sandbox/domains/search

Body:

{ "domain": "example.com" }

3.2 Order¶

POST /sandbox/domains/order

Body (example):

{
  "domain":"example.com",
  "years":1,
  "owner":{"first_name":"Valentine","last_name":"Onyemachi","email":"dev@airfreeng.com","phone":"+2348000000000","country":"NG"}
}

3.3 Checkout¶

POST /sandbox/domains/checkout

Body (example):

{
  "order_id":"<ORDER_ID>",
  "payment":{"method":"test","reference":"airfree_demo_0001"}
}

4. Common errors¶

401 Unauthorized: missing/invalid key
403 Forbidden: key lacks permission (e.g. sandbox.search)
422 Validation errors
429 Rate limit exceeded

Appendix A — Integration Quickstart (source)¶

HostivaPro Domain Center — API Integration Quickstart (Airfree Cloud + Resellers)¶

Last updated: 2026-02-27

This doc is written for Airfree Cloud developers to ship a working demo in under 1 hour (domain search → order → checkout), and for Celteck Cloud + other SaaS resellers to integrate the same flow using their own tenant + branded sandbox URL.

0) What you’re integrating¶

HostivaPro provides:

Sandbox domain API (safe, deterministic, developer/test scenarios)
Sandbox UI (branded “Domain Center” UI your reseller can access via a custom URL)
Registrar API (future / production integration; kill-switch protected)
Developer Portal (keys + analytics + kill switch)

For the quick win, use: - ✅ Sandbox API: /api/v1/sandbox/domains/*

1) Environments & URLs¶

Core API host (always use this for API calls)¶

Base URL - https://core.hostiva.quantumdevlabs.com/api/v1

Developer Portal (keys, analytics, docs)¶

https://core.hostiva.quantumdevlabs.com/developer

Branded Sandbox UI (per reseller)¶

Hostiva supports branded subdomains like:

https://sandbox.hostiva.quantumdevlabs.com (default UI)
https://airfree.sandbox.hostiva.quantumdevlabs.com (Airfree branded UI)
https://celteck.sandbox.hostiva.quantumdevlabs.com (Celteck branded UI)

Your internal reseller-friendly mapping can also exist (recommended), e.g.:

https://sandbox.cloud.airfreeng.com → CNAME to airfree.sandbox.hostiva.quantumdevlabs.com
https://sandbox.cloud.celteck.com → CNAME to celteck.sandbox.hostiva.quantumdevlabs.com

Rule: UI domain may be branded, but API calls still go to CORE base URL.

2) Authentication & tenancy¶

All API requests require:

Headers (required)¶

Authorization: Bearer <DEVKEY>
X-Tenant: <TENANT_SLUG>
Accept: application/json
Content-Type: application/json

Tenant slug¶

Examples: - Airfree Cloud: X-Tenant: airfree (or hostiva if you haven’t split tenants yet) - Celteck Cloud: X-Tenant: celteck - Default: X-Tenant: hostiva

Important: The API key must belong to the same tenant_slug as the request’s X-Tenant.

3) Getting a Sandbox API Key (fast)¶

Option A — Use the Developer Portal (recommended)¶

1) Go to: https://core.hostiva.quantumdevlabs.com/developer/keys 2) Create a key with scope: sandbox 3) Ensure permissions include: - sandbox.search - sandbox.order - sandbox.checkout 4) Copy the key (shown once). Store it in Airfree Cloud .env.

Option B — (temporary) single shared demo key¶

If you maintain a “demo key” for quick demos, set it on the UI side and restrict rate/permissions heavily.

4) Sandbox API — Endpoints¶

4.1 Domain Search¶

POST /sandbox/domains/search

Body

{ "domain": "example.com" }

Responses (example)

{
  "query": "example.com",
  "status": "available",
  "tld": "com",
  "price": { "currency": "USD", "register": 9.99, "renew": 11.99, "transfer": 9.99 },
  "meta": { "source": "hostiva-sandbox" }
}

4.2 Create Order (Reserve/Register intent)¶

POST /sandbox/domains/order

Body (example)

{
  "domain": "example.com",
  "years": 1,
  "owner": {
    "first_name": "Valentine",
    "last_name": "Onyemachi",
    "email": "dev@airfreeng.com",
    "phone": "+2348000000000",
    "country": "NG"
  }
}

Response (example)

{
  "order_id": "sbx_ord_01HZZ...",
  "domain": "example.com",
  "status": "created",
  "amount": { "currency": "USD", "total": 9.99 },
  "meta": { "source": "hostiva-sandbox" }
}

4.3 Checkout (Payment simulation + finalize)¶

POST /sandbox/domains/checkout

Body (example)

{
  "order_id": "sbx_ord_01HZZ...",
  "payment": {
    "method": "test",
    "reference": "airfree_demo_0001"
  }
}

Response (example)

{
  "order_id": "sbx_ord_01HZZ...",
  "status": "paid",
  "domain_status": "registered",
  "meta": { "source": "hostiva-sandbox" }
}

5) Copy‑paste curl examples (Airfree devs can run now)¶

Set these once:

BASE="https://core.hostiva.quantumdevlabs.com/api/v1"
TENANT="airfree"   # or "hostiva" if not separated yet
KEY="sbx_xxx..."

Search¶

curl -sk "$BASE/sandbox/domains/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -H "Authorization: Bearer $KEY" \
  --data-raw '{"domain":"example.com"}'

Order¶

curl -sk "$BASE/sandbox/domains/order" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -H "Authorization: Bearer $KEY" \
  --data-raw '{
    "domain":"example.com",
    "years":1,
    "owner":{"first_name":"Valentine","last_name":"Onyemachi","email":"dev@airfreeng.com","phone":"+2348000000000","country":"NG"}
  }'

Checkout¶

curl -sk "$BASE/sandbox/domains/checkout" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -H "Authorization: Bearer $KEY" \
  --data-raw '{
    "order_id":"<ORDER_ID_FROM_ORDER_RESPONSE>",
    "payment":{"method":"test","reference":"airfree_demo_0001"}
  }'

6) Common errors (and what they mean)¶

401 Unauthorized (developer api key missing/invalid)¶

Key not sent, wrong header, wrong key, or key doesn’t exist in DB. Fix:
Confirm you are sending Authorization: Bearer <key>
Confirm key exists and is active
Confirm hashing/pepper is stable (server-side)

403 Forbidden (scope permission denied)¶

The key exists but lacks permission for the action (e.g., search). Fix:
In Developer Portal → Keys → enable required permissions for that scope.

429 Rate limit exceeded¶

The key’s per-minute limit is reached. Fix:
Increase key rate limit (admin), or retry after a minute.

503 Live registrar API disabled¶

Kill switch is off for live registrar endpoints. Fix:
Developer Portal → toggle live kill-switch.

7) Test scenarios (for thorough demo + QA)¶

Run these tests for every reseller tenant (Airfree, Celteck, …).

7.1 Domain Search cases¶

1) Available: example.com 2) Taken: taken-example.com (or any deterministic “taken” fixture you chose) 3) Premium: premium-example.com 4) Invalid domain: @@@.com (expect 422) 5) Unsupported TLD: example.invalidtld (expect 422 or unsupported_tld)

7.2 Order cases¶

1) Order with valid owner → success 2) Order missing owner email → 422 validation error 3) Order for taken domain → 409 conflict or business error

7.3 Checkout cases¶

1) Checkout success → domain registered 2) Checkout with unknown order_id → 404 3) Checkout with duplicate payment reference → idempotency test (should be safe)

7.4 Permission enforcement¶

1) Remove sandbox.search permission and verify POST /search returns 403. 2) Restore permissions and verify success.

7.5 Rate limit¶

1) Fire 80 requests quickly (if limit is 60/min) → expect 429. 2) Confirm events/usage log increments (analytics page).

8) Reseller onboarding checklist (clean + uniform)¶

For each reseller (Airfree, Celteck, …):

1) Create tenant slug: airfree, celteck, etc. 2) Create sandbox key(s) under that tenant: - Scope: sandbox - Permissions: search/order/checkout 3) Provide reseller with: - X-Tenant value - DEVKEY value (store in their backend .env) - Branded UI URL 4) Optional: CNAME their preferred domain: - sandbox.cloud.<reseller-domain> → <reseller>.sandbox.hostiva.quantumdevlabs.com 5) Confirm their API calls always use: - https://core.hostiva.quantumdevlabs.com/api/v1

9) Integration notes for Airfree Cloud (frontend + backend)¶

Recommended architecture¶

Frontend (Airfree Cloud UI): calls Airfree backend only.
Backend (Airfree API): securely calls HostivaPro Sandbox API with DEVKEY.
Do not expose DEVKEY in browser.

Minimal endpoints Airfree should implement (internal)¶

POST /api/domains/search → forwards to Hostiva sandbox/domains/search
POST /api/domains/order → forwards to Hostiva sandbox/domains/order
POST /api/domains/checkout → forwards to Hostiva sandbox/domains/checkout

This gives you a clean boundary and lets you add billing/payment later.

Print/share these pages from Developer Portal: - Developer / Quickstart: integration overview - Developer / Keys: key creation + permission model - Developer / Sandbox: endpoint list + examples - Developer / Analytics: usage, rate limits, suspicious signals

For immediate handoff, this document is enough to ship the demo.

Support notes¶

If an integrator is stuck, ask them for: - Their X-Tenant value - Which endpoint they’re calling - The exact response JSON (401/403/429/etc.) - A curl reproduction with headers (no secrets pasted into public chat)