Docs
Developer Portal

API reference

Domains

Add, check, redirect, move and remove custom domains, and connect Cloudflare by sign-in or API token.
Read the Guide
GET/v1/orgs/:orgId/domains

Lists custom domains, and target: the hostname to point their CNAME records at.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
domains:read
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/domains' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  domains: {
    message?: string
    status?: "error" | "active" | "pending" | "verifying"
    createdAt?: number
    updatedAt?: number
    orgId: string
    projectId: string
    hostname: string
    tenantId?: string
    certificateArn?: string
    records?: string
    zone?: string
    dnsProvider?: string
    checkedAt?: number
    redirectTo?: string
    move?: boolean
    acmCertificateArn?: string
  }[]
  target: string
}
POST/v1/orgs/:orgId/domains

Adds a custom domain to a Serverless App Service and returns the DNS record to create.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
domains:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • hostnamestringrequired

    Matches ^(?=.{4,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$. Lowercased.

  • projectIdstringrequired
  • moveboolean

    Default false.

Errors

  • 400Platform hostnames can't be added as custom domains.
  • 404Serverless App Service not found
  • 409This domain is already in use.
  • 502Couldn't set up this domain. Try again.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/domains' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "hostname": "Example",
    "projectId": "<projectId>"
  }'
Send it from this page with your session or a key.

Response 201

{
  domain: {
    message?: string
    status?: "error" | "active" | "pending" | "verifying"
    createdAt?: number
    updatedAt?: number
    orgId: string
    projectId: string
    hostname: string
    tenantId?: string
    certificateArn?: string
    records?: string
    zone?: string
    dnsProvider?: string
    checkedAt?: number
    redirectTo?: string
    move?: boolean
    acmCertificateArn?: string
  }
  records: {
    type: "CNAME" | "TXT"
    name: string
    value: string
    purpose?: "validation"
  }[]
  dns?: {
    ok: boolean
    expected: string
    found: string[]
  }
}
POST/v1/orgs/:orgId/domains/:hostname/verify

Checks the domain's certificate and updates its status.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
domains:read
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • hostname

    The custom domain.

Errors

  • 404Domain not found
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/domains/{hostname}/verify' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  domain: {
    message?: string
    status?: "error" | "active" | "pending" | "verifying"
    createdAt?: number
    updatedAt?: number
    orgId: string
    projectId: string
    hostname: string
    tenantId?: string
    certificateArn?: string
    records?: string
    zone?: string
    dnsProvider?: string
    checkedAt?: number
    redirectTo?: string
    move?: boolean
    acmCertificateArn?: string
  }
}
| {
  domain: {
    message?: string
    status?: "error" | "active" | "pending" | "verifying"
    createdAt?: number
    updatedAt?: number
    orgId: string
    projectId: string
    hostname: string
    tenantId?: string
    certificateArn?: string
    records?: string
    zone?: string
    dnsProvider?: string
    checkedAt?: number
    redirectTo?: string
    move?: boolean
    acmCertificateArn?: string
  }
  dns?: undefined
} | {
  domain: {
    message?: string
    status?: "error" | "active" | "pending" | "verifying"
    createdAt?: number
    updatedAt?: number
    orgId: string
    projectId: string
    hostname: string
    tenantId?: string
    certificateArn?: string
    records?: string
    zone?: string
    dnsProvider?: string
    checkedAt?: number
    redirectTo?: string
    move?: boolean
    acmCertificateArn?: string
  }
  dns: {
    ok: boolean
    expected: string
    found: string[]
  }
}
POST/v1/orgs/:orgId/domains/:hostname/cloudflare

Creates the domain's records with the org's connected Cloudflare token, then checks right away. Create-only: a record already pointing elsewhere is replaced only for an owner or admin (a move's second click, say); for anyone else nothing is written and the answer names it (409), so the connection never repoints a live record for someone who may only add one.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
domains:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • hostname

    The custom domain.

Errors

  • 400This domain's zone couldn't be found in DNS.
  • 400Connect Cloudflare first.
  • 404Domain not found
  • 409… An owner or admin can replace … here, or change … in Cloudflare.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/domains/{hostname}/cloudflare' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  domain: {
    message?: string
    status?: "error" | "active" | "pending" | "verifying"
    createdAt?: number
    updatedAt?: number
    orgId: string
    projectId: string
    hostname: string
    tenantId?: string
    certificateArn?: string
    records?: string
    zone?: string
    dnsProvider?: string
    checkedAt?: number
    redirectTo?: string
    move?: boolean
    acmCertificateArn?: string
  }
  dns?: undefined
} | {
  domain: {
    message?: string
    status?: "error" | "active" | "pending" | "verifying"
    createdAt?: number
    updatedAt?: number
    orgId: string
    projectId: string
    hostname: string
    tenantId?: string
    certificateArn?: string
    records?: string
    zone?: string
    dnsProvider?: string
    checkedAt?: number
    redirectTo?: string
    move?: boolean
    acmCertificateArn?: string
  }
  dns: {
    ok: boolean
    expected: string
    found: string[]
  }
}
PATCH/v1/orgs/:orgId/domains/:hostname

Moves a domain to another Serverless App Service of the org, or makes it redirect to another domain of its Serverless App Service (redirectTo: null serves the Serverless App Service again). The edge route changes right away.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
domains:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • hostname

    The custom domain.

Request body

  • projectIdstring

    At least 1 character.

  • redirectTostringor null

    Matches ^(?=.{4,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$. Lowercased.

Errors

  • 400A domain can't redirect to itself.
  • 400Redirect to another domain of the same Serverless App Service.
  • 400… redirects too. Choose a domain that serves the Serverless App Service.
  • 404Domain not found
  • 404Serverless App Service not found
  • 409… redirects to this domain. Change that first.
curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/domains/{hostname}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "projectId": "<projectId>",
    "redirectTo": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  domain: {
    message?: string
    status?: "error" | "active" | "pending" | "verifying"
    createdAt?: number
    updatedAt?: number
    orgId: string
    projectId: string
    hostname: string
    tenantId?: string
    certificateArn?: string
    records?: string
    zone?: string
    dnsProvider?: string
    checkedAt?: number
    redirectTo?: string
    move?: boolean
    acmCertificateArn?: string
  }
}
DELETE/v1/orgs/:orgId/domains/:hostname

Removes a custom domain: its route and its certificate.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
domains:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • hostname

    The custom domain.

Errors

  • 404Domain not found
  • 409… redirects to this domain. Change that first.
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/domains/{hostname}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/orgs/:orgId/integrations/cloudflare

Whether Cloudflare is connected (by sign-in or API token), the zones it can see, whether a sign-in grant expired, and whether sign-in is available. Credentials are never returned.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
domains:read
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/integrations/cloudflare' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  connected: boolean
  kind: null | "token" | "oauth"
  zones: string[]
  connectedAt?: number
  expired: boolean
  oauth: boolean
}
POST/v1/orgs/:orgId/integrations/cloudflare/authorize

Starts the OAuth flow: stores a one-time state and returns Cloudflare's authorize URL.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
domains:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • returnTostring

    Up to 500 characters.

  • offlineboolean

    Default true.

Errors

  • 403Connecting Cloudflare needs a signed-in user.
  • 501Cloudflare sign-in isn't available. Use an API token instead.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/integrations/cloudflare/authorize' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "returnTo": "example",
    "offline": true
  }'
Send it from this page with your session or a key.

Response 200

{
  url: string
}
POST/v1/orgs/:orgId/integrations/cloudflare/oauth

Completes the OAuth flow. The state is consumed first (one use), then checked against this user and org. With error instead of code (the user declined), it only consumes the state and returns where to go back to; retry says to start again without offline access.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
domains:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • statestringrequired

    10–300 characters.

  • codestring

    1–2,000 characters.

  • errorstring

    Up to 200 characters.

Errors

  • 422Cloudflare didn't share any zones. Choose the zones you'll use when you allow access.
  • 501Cloudflare sign-in isn't available.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/integrations/cloudflare/oauth' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "state": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  connected: false
  returnTo: string
  retry: boolean
}
| {
  connected: true
  zones: string[]
  returnTo: string
  refresh: boolean
}
PUT/v1/orgs/:orgId/integrations/cloudflare

Connects a Cloudflare API token (Zone → DNS → Edit) for adding domain records. The token is checked against Cloudflare, encrypted and stored; it must see at least one zone.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
domains:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • tokenstringrequired

    20–200 characters. Trimmed.

Errors

  • 400The token can't see any zones. Give it Zone → DNS → Edit on the zones you'll use.
curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/integrations/cloudflare' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  connected: true
  kind: string
  zones: string[]
}
DELETE/v1/orgs/:orgId/integrations/cloudflare

Disconnects Cloudflare: revokes a sign-in grant at Cloudflare (best effort) and deletes the stored credentials.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
domains:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/integrations/cloudflare' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body