• All requests must be issued over HTTPS
• All requests require authentication via an API token in the URL path
• Request and response bodies are application/json

The SSLforSaaS API applies rate limits per API key. If you exceed the limit you will receive a 429 Too Many Requests response. Check your plan limits in the dashboard.

Validation errors occur when one or more required fields are missing or invalid. Returns a 409 Conflict.

{
  "required_field": [
    "This field is required."
  ]
}

Authentication errors occur when no token is provided, the token is invalid, or the token lacks permission for the requested resource.

Missing or invalid token — 403 Forbidden

{
  "description": "Please provide an auth token as part of the request.",
  "title": "Invalid api key"
}

Insufficient permissions — 401 Unauthorized

{
  "message": "You do not have the required permission to access this resource"
}

Replace {API_KEY} with your SSLforSaaS token from the API settings page of your dashboard.

You can find the endpoint reference key on the project settings page of your SSLforSaaS dashboard.

curl -XPOST -H "Content-type: application/json" \
     -d '{
  "domain": "customer.example.com",
  "endpoint": "{ENDPOINT_REF}"
}' \
     'https://api.sslforsaas.io/v1/{API_KEY}/tls'

Replace {API_KEY} with your SSLforSaaS API token.

curl -XPOST -H "Content-type: application/json" \
     -d '{
  "domain": "customer.example.com"
}' \
     'https://api.sslforsaas.io/v1/{API_KEY}/disable'

Unlike SSLforSaaS-managed certificates — where issuance and renewal are fully automated — custom certificates put you in charge of the following:

• Uploading the Certificate — add your certificate via the dashboard or API.
• Updating the Certificate — when renewing, you must push the new certificate to SSLforSaaS.
• Monitoring Expiry — SSLforSaaS does not auto-renew custom certificates. You are responsible for tracking the expiration date.

SSLforSaaS validates every custom certificate before accepting it. Your certificate must:

• Be encoded in PEM format
• Have a Subject Alternative Name (SAN) matching the target domain
• Not expire within 14 days of the upload date
• Not have a password-protected private key

• Go to Domains and select the relevant domain
• Click Add certificate
• Paste or drag-and-drop your PEM certificate and private key
• Click Next — SSLforSaaS validates the certificate automatically

Adding a certificate

curl -X POST -H "Content-type: application/json" \
     -d '{
  "display_name": "My custom cert",
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "domain": "customer.example.com"
}' \
     'https://api.sslforsaas.io/v1/{API_KEY}/certificate/add'

Updating a certificate

curl -X POST -H "Content-type: application/json" \
     -d '{
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "domain": "customer.example.com"
}' \
     'https://api.sslforsaas.io/v1/{API_KEY}/certificate/update'

Removing a certificate

curl -X POST -H "Content-type: application/json" \
     -d '{
  "domain": "customer.example.com"
}' \
     'https://api.sslforsaas.io/v1/{API_KEY}/certificate/remove'

All webhook payloads share the same top-level structure:

• event — the type of event that occurred
• data.id — the unique ID of the affected resource
• data.status — the current status
• data.url — the domain name
• data.endpoint — project endpoint details (if applicable)
• data.timestamp — ISO 8601 timestamp of the event

domain.created

{
  "event": "domain.created",
  "data": {
    "id": "907589706",
    "url": "customer.example.com",
    "endpoint": {},
    "timestamp": "2024-06-16T14:58:47Z",
    "admin_graphql_api_id": "gid://sslforsaas/Domain/907589706"
  }
}

domain.disabled

{
  "event": "domain.disabled",
  "data": {
    "id": "907589706",
    "url": "customer.example.com",
    "endpoint": {},
    "timestamp": "2024-06-16T15:12:00Z"
  }
}

domain.deleted

{
  "event": "domain.deleted",
  "data": {
    "id": "907589706",
    "url": "customer.example.com",
    "timestamp": "2024-06-16T16:00:00Z"
  }
}

Your webhook URL is a standard POST endpoint that parses a JSON body and returns 200 OK.

app.post("/sslforsaas-webhook", (req, res) => {
  // Verify signature
  const secretHash = process.env.SSLFORSAAS_SECRET_HASH;
  const signature = req.headers["x-sslforsaas-signature"];
  if (!signature || signature !== secretHash) {
    return res.status(401).end();
  }
  const payload = req.body;
  console.log("SSLforSaaS event:", payload.event);
  // Process event asynchronously …
  res.status(200).end();
});

• Log in to your SSLforSaaS dashboard
• Go to Workspace Settings → Webhooks
• Add your webhook URL and an optional secret hash
• Save your settings

Use a secret hash

Your webhook URL is publicly accessible. Set a secret hash in your SSLforSaaS dashboard and verify the x-sslforsaas-signature header on every incoming request.

Respond quickly

Return a 200 OK as fast as possible. Dispatch long-running tasks to a background queue. Without a timely response, SSLforSaaS will retry for up to 36 hours.

Be idempotent

Occasionally SSLforSaaS may deliver the same event more than once. Record processed event IDs and skip duplicates gracefully.

By default all provisioned domains route traffic to the single application endpoint configured on your SSLforSaaS project. A custom origin server lets you specify a per-domain target endpoint at provisioning time.

Example:

• customer-a.example.com → origin-a.your-backend.io
• customer-b.example.com → origin-b.your-backend.io

Add a "target" parameter to the provisioning request body:

curl -XPOST -H "Content-type: application/json" \
     -d '{
  "domain": "customer.example.com",
  "target": "origin-a.your-backend.io"
}' \
     'https://api.sslforsaas.io/v1/{API_KEY}/tls'

curl -XGET -H "Content-type: application/json" \
     'https://api.sslforsaas.io/v1/{API_KEY}/domain/list?page=1'

Sample Response

{
  "domains": [
    {
      "id": 1,
      "name": "www.example.com",
      "dns_status": "CONNECTED",
      "status": "ENABLED"
    },
    {
      "id": 2,
      "name": "shop.acme.io",
      "dns_status": "DISCONNECTED",
      "status": "DISABLED"
    }
  ],
  "page": 1,
  "total_pages": 5,
  "total_domains": 2500
}

Filter by DNS status

curl -XGET 'https://api.sslforsaas.io/v1/{API_KEY}/domain/list?dns_status=CONNECTED'

Filter by operational status

curl -XGET 'https://api.sslforsaas.io/v1/{API_KEY}/domain/list?status=ENABLED'

Combine both filters

curl -XGET 'https://api.sslforsaas.io/v1/{API_KEY}/domain/list?dns_status=CONNECTED&status=ENABLED'

SSLforSaaS integrates with the following trusted CAs. Select your preferred CA from your project settings page.

Both Let's Encrypt and ZeroSSL are trusted by all major browsers and operating systems. The choice typically depends on:

• Issuance speed — both offer near-instant DV certificate issuance
• Rate limits — Let's Encrypt applies per-domain rate limits; ZeroSSL has higher default limits on paid plans
• Compliance requirements — some enterprise environments prefer ZeroSSL for commercial CA support