• All requests must be issued over HTTPS.
• Project API requests use Authorization: ApiKey {PROJECT_API_KEY}.
• All project API routes include {workspaceId} and {projectId}.
• Domain creation and enable transitions are asynchronous and can return 202 Accepted.
• Request and response bodies are application/json.

No plan-specific request throttling contract is currently published. If infrastructure returns 429 Too Many Requests, retry with backoff and preserve idempotency on your side.

Validation errors occur when a request body, identifier, or query parameter is missing or invalid.

{
  "message": "Invalid request body"
}

Authorization errors occur when the project API key is missing, invalid, revoked, inactive, or lacks the required scope.

{
  "message": "Forbidden"
}

Requires the domains:write scope.

{
  "message": "Domain creation accepted and queued for asynchronous provisioning.",
  "domain_id": "65f000000000000000000001",
  "operation_id": "8b39f8a3-6f1b-4e85-8d4e-a8711a9e52d1",
  "cname_target": "project-id.sslforsaas.io",
  "provisioning": {
    "state": "queued",
    "hostname_status": "pending",
    "certificate_status": "pending"
  }
}

The returned cname_target is the customer-facing project CNAME, also available as cname_domain from GET /workspaces/{workspaceId}/projects/{projectId}. Do not point customer DNS at your application origin or an internal load-balancer hostname.

Requires the domains:write scope.

A project API key can work with domain lifecycle endpoints according to its declared scopes:

• Add a customer domain to a project.
• Read persisted DNS, hostname, and certificate status.
• Check a registered domain's latest certificate status with GET /workspaces/{workspaceId}/projects/{projectId}/domains/{domainId}?check_status=1. A refresh can update the saved lifecycle state.
• Disable a domain before deleting it.

Configure webhooks from the project settings page. Owners and admins can set a webhook URL, enable/disable delivery, set a signing secret, and choose event types.

• Webhook settings are project-scoped.
• System events are visible in the notification catalog but are not project-webhook subscribable by default.
• Webhook secrets are used to sign each delivery attempt.

Outbound webhook deliveries include notification fields and a stable event_id inside the signed JSON body:

{
  "event_id": "65f000000000000000000002",
  "event_type": "workspace.domain_disabled",
  "scope": "workspace_event",
  "severity": "high",
  "title": "Domain disabled",
  "message": "Domain customer.example.com has been disabled.",
  "source": "domains.update",
  "workspace_id": "{workspaceId}",
  "project_id": "{projectId}",
  "payload": {
    "domain_id": "{domainId}",
    "domain_name": "customer.example.com"
  },
  "occurred_at": "2026-06-22T10:00:00Z"
}

Verify signatures

Recompute the HMAC with your webhook secret over {timestamp}.{rawBody} and compare it to X-SSLforSaaS-Signature.

Respond quickly

Return 2xx quickly and process long-running work asynchronously. SSLforSaaS retries transient delivery failures; use the signed event_id to avoid duplicate processing.

Be idempotent

Retries carry the same event_id. After verifying the signature, use the signed body's event_id to record processed events and skip duplicates. The X-SSLforSaaS-Event-Id header mirrors that value but is not itself signed. Delivery is not exactly-once.

When a domain is added to a project, SSLforSaaS uses the project's Cloudflare and routing mapping to direct traffic to the configured application endpoint. The domain create API does not currently accept a per-domain target parameter.

• Project application endpoint is the source of truth for origin routing.
• Domain create returns the authoritative CNAME/target information for customer DNS setup.
• Change the application endpoint in project settings; the updated route may take time to become active.

Requires the project:read scope.

Requires the domains:read scope.

curl -X GET \
     -H "Authorization: ApiKey {PROJECT_API_KEY}" \
     'https://api.sslforsaas.io/workspaces/{workspaceId}/projects/{projectId}/domains?page=1&limit=20'

Sample Response

{
  "total": 2,
  "page": 1,
  "pages": 1,
  "domains": [
    {
      "_id": "65f000000000000000000001",
      "domain_name": "customer.example.com",
      "status": true,
      "ssl_status": "active",
      "provisioning": {
        "state": "active"
      }
    }
  ]
}