CertWarden Public API

Base URL: https://certwarden.perim.net

All Public API endpoints are prefixed with /api/v1/ and require Bearer token authentication.

---

Authentication

Public API uses Bearer token authentication:

Authorization: Bearer <your_api_token>

API tokens are created via the CertWarden Mobile API (Pro plan required). The Public API does not provide token-creation endpoints.

---

Table of Contents

• Domains
• Groups
• Status

---

Domains

List Domains

GET /api/v1/domains

Returns all domains associated with the API token.

Response (200)

{
  "success": true,
  "data": {
    "domains": [
      {
        "id": "7ef88ae6-7586-45c0-9bf4-ff0deddca573",
        "hostname": "example.com",
        "port": 443,
        "groups": [],
        "certificate": {
          "issuer": "Let’s Encrypt",
          "valid_from": "2026-01-01T00:00:00.000Z",
          "valid_until": "2026-04-01T23:59:59.000Z",
          "days_remaining": 60,
          "status": "valid",
          "last_checked_at": "2026-02-12T21:00:45.058Z"
        }
      }
    ],
    "total": 1
  }
}

Field Notes

• hostname is the domain name (without scheme).
• port is the TLS port checked (typically 443).
• groups is an array of group references (may be empty).
• certificate.status is one of: valid, expiring, expired, unknown.
• All timestamps are ISO-8601 in UTC.

---

Get Domain Details

GET /api/v1/domains/{id}

Returns details for a specific domain.

---

Trigger Manual Check

POST /api/v1/domains/{id}/check

Triggers an on-demand certificate check for the given domain.

---

Groups

List Groups

GET /api/v1/groups

Returns all domain groups.

Response (200)

{
  "success": true,
  "data": {
    "groups": [
      {
        "id": "384fb15b-e3fb-4490-bb58-fcdf992f0d48",
        "name": "Production",
        "color": "#34C759",
        "domain_count": 3
      }
    ],
    "total": 1
  }
}

Field Notes

• color is a HEX color string used for UI labeling.
• domain_count is the number of domains currently assigned to the group.

---

Status

Service Status

GET /api/v1/status

Returns a summary of certificate statuses across all domains associated with the API token.

Response (200)

{
  "success": true,
  "data": {
    "summary": {
      "total_domains": 5,
      "valid": 3,
      "expiring": 1,
      "expired": 1,
      "error": 0
    }
  }
}

Field Notes

• total_domains is the total number of monitored domains.
• valid, expiring, expired, and error represent the current certificate state counts.

---

Error Handling

Errors are returned in a consistent envelope.

Example (401)

{
  "success": false,
  "error": {
    "message": "Invalid token",
    "code": 401
  }
}

---

Rate Limiting

Requests are rate-limited per API token. If the limit is exceeded, the API will return HTTP 429 Too Many Requests.

---

Notes

• The Public API is read-focused and intended for external integrations.
• Token management and webhooks are configured via the mobile app.
• No personal data is exposed through the Public API.