API Documentation

Integrate SSL and certificate monitoring into your applications

Get API Key Quick Start

Quick Start

Base URL

https://sslbeacon.com/api/v1

1. Create an API Key

Generate an API key from your dashboard. Get API Key

2. Make Your First Request

Use your API key in the Authorization header to list your monitored domains.

bash

curl -X GET "https://sslbeacon.com/api/v1/domains" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

3. Parse the Response

Every response returns a JSON object with a success flag and a data field.

json

{
  "success": true,
  "data": [
    {
      "id": "abc-123",
      "domainName": "example.com",
      "sslExpiryDate": "2026-06-15T00:00:00.000Z",
      "status": "active"
    }
  ],
  "meta": { "count": 1 }
}

Authentication

All API requests require an API key sent via the Authorization header. Keys use the sk_live_ prefix format.

Authorization Header

http

Authorization: Bearer sk_live_xxxxxxxxxxxxx

Permissions

read

Can list and retrieve resources (GET endpoints)

write

Can create, delete, and trigger actions (POST/DELETE endpoints)

Security: Never expose API keys in client-side code. Always make API calls from your server.

Rate Limits

API requests are rate-limited to ensure fair usage across all accounts.

Per-Minute Limit

60 requests per minute per API key

Monthly Limits by Plan

Starter1,000/mo
Professional10,000/mo
Enterprise100,000/mo

Rate Limit Headers

http

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1709251200

Error Handling

The API uses standard HTTP status codes. All error responses include a consistent JSON structure.

Status	Description
`200`	Success
`201`	Created — resource successfully created
`400`	Bad Request — invalid parameters or body
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — insufficient permissions
`404`	Not Found — resource does not exist
`429`	Rate Limit Exceeded — too many requests
`500`	Internal Server Error

Error Response Format

json

{
  "success": false,
  "error": "domainName is required"
}

Validation errors (400) include a details array:

json

{
  "success": false,
  "error": "Invalid request body",
  "details": [
    {
      "path": ["domainName"],
      "message": "Required"
    }
  ]
}

Domains API

Manage your monitored domains. Add, remove, and check SSL status.

GET/api/v1/domainsread

Retrieve all domains you are monitoring.

Response

json

{
  "success": true,
  "data": [
    {
      "id": "abc-123",
      "domainName": "example.com",
      "sslExpiryDate": "2026-06-15T00:00:00.000Z",
      "domainExpiryDate": "2027-01-20T00:00:00.000Z",
      "lastCheckedAt": "2026-03-12T10:30:00.000Z",
      "nextCheckAt": "2026-03-12T11:30:00.000Z",
      "status": "active",
      "createdAt": "2025-01-15T08:00:00.000Z",
      "updatedAt": "2026-03-12T10:30:00.000Z"
    }
  ],
  "meta": { "count": 1 }
}

POST/api/v1/domainswrite

Add a new domain to your monitoring list. An initial SSL check is triggered automatically.

Request Body

Name	Type	Required	Description
domainName	string	Required	Domain name to monitor (1-253 characters)

Response `201`

json

{
  "success": true,
  "message": "Domain added successfully",
  "data": {
    "id": "abc-124",
    "domainName": "example.com",
    "status": "active",
    "createdAt": "2026-03-12T12:00:00.000Z"
  }
}

GET/api/v1/domains/:idread

Get detailed information about a domain including its current SSL certificate status.

Path Parameters

Name	Type	Required	Description
id	string	Required	Domain ID

Response

json

{
  "success": true,
  "data": {
    "id": "abc-123",
    "domainName": "example.com",
    "ssl": {
      "expiryDate": "2026-06-15T00:00:00.000Z",
      "daysRemaining": 95,
      "status": "healthy"
    },
    "domainExpiry": {
      "expiryDate": "2027-01-20T00:00:00.000Z",
      "daysRemaining": 314,
      "status": "healthy"
    },
    "lastCheckedAt": "2026-03-12T10:30:00.000Z",
    "nextCheckAt": "2026-03-12T11:30:00.000Z",
    "status": "active"
  }
}

SSL Status Values

SSL certificate expiry thresholds:

healthy — more than 30 days until expiry
warning — 8 to 30 days until expiry
critical — 1 to 7 days until expiry
expired — certificate has expired
unknown — not yet checked

Domain expiry thresholds (different from SSL):

healthy — more than 90 days until expiry
warning — 31 to 90 days until expiry
critical — 1 to 30 days until expiry
expired — domain has expired
unknown — not yet checked

DELETE/api/v1/domains/:idwrite

Remove a domain from monitoring. This also deletes all associated check history.

Path Parameters

Name	Type	Required	Description
id	string	Required	Domain ID

Response

json

{
  "success": true,
  "message": "Domain removed successfully"
}

POST/api/v1/domains/:id/checkwrite

Trigger an immediate SSL check for a specific domain instead of waiting for the next scheduled check.

Path Parameters

Name	Type	Required	Description
id	string	Required	Domain ID

Response

json

{
  "success": true,
  "message": "SSL check completed successfully",
  "data": {
    "id": "abc-123",
    "domainName": "example.com",
    "ssl": {
      "expiryDate": "2026-06-15T00:00:00.000Z",
      "daysRemaining": 95,
      "checkSuccess": true
    },
    "lastCheckedAt": "2026-03-12T12:05:00.000Z",
    "nextCheckAt": "2026-03-12T13:05:00.000Z",
    "status": "active"
  }
}

Certificates API

Query certificate data, find expiring certificates, and check overall health.

GET/api/v1/certificatesread

List all SSL certificates with summary statistics across your monitored domains.

Response

json

{
  "success": true,
  "data": {
    "certificates": [
      {
        "id": "abc-123",
        "domainName": "example.com",
        "expiryDate": "2026-06-15T00:00:00.000Z",
        "daysRemaining": 95,
        "status": "healthy",
        "lastCheckedAt": "2026-03-12T10:30:00.000Z"
      }
    ],
    "summary": {
      "total": 5,
      "healthy": 3,
      "warning": 1,
      "critical": 0,
      "expired": 0,
      "unknown": 1
    }
  },
  "meta": { "count": 5 }
}

GET/api/v1/certificates/:idread

Get full details of a specific SSL certificate including expiry and monitoring status.

Path Parameters

Name	Type	Required	Description
id	string	Required	Domain ID

Response

json

{
  "success": true,
  "data": {
    "id": "abc-123",
    "domainName": "example.com",
    "ssl": {
      "expiryDate": "2026-06-15T00:00:00.000Z",
      "daysRemaining": 95,
      "status": "healthy"
    },
    "domain": {
      "expiryDate": "2027-01-20T00:00:00.000Z",
      "daysRemaining": 314,
      "status": "healthy"
    },
    "monitoring": {
      "lastCheckedAt": "2026-03-12T10:30:00.000Z",
      "nextCheckAt": "2026-03-12T11:30:00.000Z",
      "status": "active"
    }
  }
}

GET/api/v1/certificates/expiringread

Find certificates expiring within a given number of days. Defaults to 30 days.

Query Parameters

Name	Type	Required	Description
days	number	Optional	Number of days to look ahead (1-365, default: 30)

Response

json

{
  "success": true,
  "data": {
    "threshold": 30,
    "certificates": [
      {
        "id": "def-456",
        "domainName": "expiring-soon.com",
        "expiryDate": "2026-04-01T00:00:00.000Z",
        "daysRemaining": 20,
        "status": "warning"
      }
    ]
  },
  "meta": { "count": 1 }
}

GET/api/v1/certificates/healthread

Get an overall health score (0–100) and breakdown of certificate statuses.

Response

json

{
  "success": true,
  "data": {
    "overallStatus": "warning",
    "healthScore": 82,
    "summary": {
      "total": 5,
      "healthy": 3,
      "warning": 1,
      "critical": 0,
      "expired": 0,
      "unknown": 1
    },
    "nextExpiring": {
      "domainName": "expiring-soon.com",
      "daysRemaining": 20
    },
    "checkedAt": "2026-03-12T12:00:00.000Z"
  }
}

Code Examples

Ready-to-use examples in popular languages. Replace YOUR_API_KEY with your actual key.

List Domains

bash

curl -X GET "https://sslbeacon.com/api/v1/domains" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Add a Domain

bash

curl -X POST "https://sslbeacon.com/api/v1/domains" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"domainName": "example.com"}'

Certificate Health

bash

curl -X GET "https://sslbeacon.com/api/v1/certificates/health" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Expiring Certificates

bash

curl -X GET "https://sslbeacon.com/api/v1/certificates/expiring?days=14" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Ready to Integrate?

Create your API key and start building integrations with SSL Beacon.

Get API Key Contact Support

API Documentation

Quick Start

1. Create an API Key

2. Make Your First Request

3. Parse the Response

Authentication

Authorization Header

Permissions

Rate Limits

Per-Minute Limit

Monthly Limits by Plan

Rate Limit Headers

Error Handling

Error Response Format

Domains API

Response

Request Body

Response 201

Path Parameters

Response

SSL Status Values

Path Parameters

Response

Path Parameters

Response

Certificates API

Response

Path Parameters

Response

Query Parameters

Response

Response

Code Examples

List Domains

Add a Domain

Certificate Health

Expiring Certificates

Ready to Integrate?

Response `201`