Custom Domains

Custom domains let you serve your app’s privacy policy and other pages from your own domain (e.g., privacy.myapp.com) instead of the default sites.orbitkit.io subdirectory.

OrbitKit automatically provisions SSL certificates via Google Certificate Manager. After setting a domain, you’ll receive DNS instructions to point your domain to OrbitKit’s servers.

Endpoints

Rate limit: 5/hour per user for domain operations.

Set custom domain

PUT /api/apps/:appId/site/domain

Assigns a custom domain to the app, provisions an SSL certificate, and returns DNS instructions.

Request body

Full example

curl -X PUT https://api.orbitkit.io/api/apps/-NtestApp123/site/domain \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "privacy.myapp.com"}'

var request = URLRequest(url: URL(string: "https://api.orbitkit.io/api/apps/\(appId)/site/domain")!)
request.httpMethod = "PUT"
request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONEncoder().encode(["domain": "privacy.myapp.com"])

let (data, _) = try await URLSession.shared.data(for: request)
let result = try JSONDecoder().decode(DnsInstructionsResponse.self, from: data)
// Show DNS records to user

const res = await fetch(`https://api.orbitkit.io/api/apps/${appId}/site/domain`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ domain: "privacy.myapp.com" }),
});
const { dnsInstructions } = await res.json();

Response

{
  "dnsInstructions": [
    {
      "type": "A",
      "name": "privacy.myapp.com",
      "value": "34.120.1.2"
    },
    {
      "type": "CNAME",
      "name": "_acme-challenge.privacy.myapp.com",
      "value": "abc123.acme.goog."
    }
  ]
}

The user must configure both DNS records at their registrar:

1. A record — points the domain to OrbitKit’s load balancer
2. CNAME record — proves domain ownership for SSL certificate provisioning

Errors

Remove custom domain

DELETE /api/apps/:appId/site/domain

Removes the custom domain and its SSL certificate. The site remains accessible via the default sites.orbitkit.io URL.

Response 204 No Content

No response body.

Check domain status

GET /api/apps/:appId/site/domain/status

Returns DNS verification and SSL provisioning status for the custom domain.

Response

{
  "domain": "privacy.myapp.com",
  "dnsVerified": true,
  "sslProvisioned": true,
  "status": "active"
}

Status values

Errors