Certificates

Download schema

Endpoints for the TLS certificates of sites and services across the team's servers, their renewal tooling and issues.

Search certificates

GET

https://server.chief.app/api/v1

/certificates

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Find certificates across the servers the authenticated team can see, including servers shared with it: which expire soon, which are not renewed automatically, which certbot or acme.sh plugin issued them, and which fail a check such as a weak key or names a site uses that the certificate does not cover. A certificate used by several sites and services of a server is listed once. Every result includes its server.

Search certificates › query Parameters

query

string | null · maxLength: 255

Only return certificates whose names, subject, issuer, CA, manager, lineage or plugin contain this text.

issue

string | null · enum

Only return certificates failing this check.

Enum values:

expiring_unmanaged

renewal_missing

staging_ca

self_signed_public

incomplete_chain

weak_key

names_not_covered

duplicate

has_issues

boolean | null

Only return certificates failing at least one check.

severity

string | null · enum

Only return certificates whose most severe issue has this severity or worse.

Enum values:

high

medium

low

expiring_days

integer | null · min: 0 · max: 3650

Only return certificates that expire within this many days, including certificates that already expired. 0 returns expired certificates only.

manager

string | null · enum

Only return certificates issued and renewed by this tool.

Enum values:

certbot

acme.sh

plesk

directadmin

forge

unmanaged

boolean | null

Only return certificates without renewal automation: none was found, or the agent could not tell.

ca

string | null · maxLength: 32

Only return certificates of this CA: letsencrypt, letsencrypt-staging, zerossl, buypass, google or sectigo. New values may be added.

plugin

string | null · maxLength: 64

Only return certificates issued with this certbot or acme.sh plugin.

sort

string | null · enum

urgency lists the most severe issues first and then the soonest expiry, expiry the soonest expiry first, name sorts by the primary name.

Enum values:

urgency

expiry

name

Default: urgency

per_page

integer · min: 1 · max: 100

page

integer · min: 1

Search certificates › Responses

Paginated set of ServerCertificate

ServerCertificate[] · required

object · required

GET/certificates

curl https://server.chief.app/api/v1/certificates \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "certificate_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "server": {
        "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "web-01"
      },
      "fingerprint": "3f6c1a9e0b7d4c2a8e5f1b3d7a9c0e2f4b6d8a1c3e5f7b9d0a2c4e6f8b1d3a5c",
      "serial": "04a1b2c3d4e5f60718293a4b5c6d7e8f9a0b",
      "subject": {
        "cn": "shop.example.com",
        "org": "org"
      },
      "issuer": {
        "cn": "R11",
        "org": "Let's Encrypt"
      },
      "not_before": "not_before",
      "not_after": "not_after",
      "expired": true,
      "days_left": 42,
      "names": [
        "shop.example.com",
        "www.shop.example.com"
      ],
      "key": {
        "type": "ecdsa",
        "bits": 256,
        "curve": "P-256"
      },
      "signature_algorithm": "ECDSA-SHA384",
      "self_signed": true,
      "chain": {
        "complete": true,
        "intermediates": 1
      },
      "paths": [
        "string"
      ],
      "used_by": [
        {
          "kind": "site",
          "ref": "apache/shop.example.com",
          "site_url": "https://server.chief.app/team/acme/sites/01j8q8zk2f4m6n7p9r1s3t5v7x/shop.example.com"
        }
      ],
      "managed_by": {
        "tool": "certbot",
        "name": "shop.example.com",
        "plugin": "dns-domainchief",
        "installer": "apache",
        "ca": "letsencrypt",
        "ca_url": "https://acme-v02.api.letsencrypt.org/directory",
        "renewal": "timer",
        "config": "/etc/letsencrypt/renewal/shop.example.com.conf"
      },
      "issues": [
        {
          "issue": "expiring_unmanaged",
          "severity": "high",
          "label": "Weak key",
          "explanation": "The key is weaker than an RSA 2048-bit or P-256 key, which clients may reject. Issue it again with a stronger key."
        }
      ],
      "severity": "high",
      "first_seen_at": "first_seen_at",
      "url": "https://server.chief.app/team/acme/certificates/01j8q8zk2f4m6n7p9r1s3t5v7x"
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

Show a certificate

GET

https://server.chief.app/api/v1

/certificates/{certificate}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Show a certificate of a server the authenticated team can see: its names, validity, key, chain, the sites and services using it, the tool renewing it and the checks it fails.

Show a certificate › path Parameters

certificate

string · required

Show a certificate › Responses

ServerCertificate

object · required

GET/certificates/{certificate}

curl https://server.chief.app/api/v1/certificates/:certificate \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "certificate_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "server": {
      "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "web-01"
    },
    "fingerprint": "3f6c1a9e0b7d4c2a8e5f1b3d7a9c0e2f4b6d8a1c3e5f7b9d0a2c4e6f8b1d3a5c",
    "serial": "04a1b2c3d4e5f60718293a4b5c6d7e8f9a0b",
    "subject": {
      "cn": "shop.example.com",
      "org": "org"
    },
    "issuer": {
      "cn": "R11",
      "org": "Let's Encrypt"
    },
    "not_before": "not_before",
    "not_after": "not_after",
    "expired": true,
    "days_left": 42,
    "names": [
      "shop.example.com",
      "www.shop.example.com"
    ],
    "key": {
      "type": "ecdsa",
      "bits": 256,
      "curve": "P-256"
    },
    "signature_algorithm": "ECDSA-SHA384",
    "self_signed": true,
    "chain": {
      "complete": true,
      "intermediates": 1
    },
    "paths": [
      "string"
    ],
    "used_by": [
      {
        "kind": "site",
        "ref": "apache/shop.example.com",
        "site_url": "https://server.chief.app/team/acme/sites/01j8q8zk2f4m6n7p9r1s3t5v7x/shop.example.com"
      }
    ],
    "managed_by": {
      "tool": "certbot",
      "name": "shop.example.com",
      "plugin": "dns-domainchief",
      "installer": "apache",
      "ca": "letsencrypt",
      "ca_url": "https://acme-v02.api.letsencrypt.org/directory",
      "renewal": "timer",
      "config": "/etc/letsencrypt/renewal/shop.example.com.conf"
    },
    "issues": [
      {
        "issue": "expiring_unmanaged",
        "severity": "high",
        "label": "Weak key",
        "explanation": "The key is weaker than an RSA 2048-bit or P-256 key, which clients may reject. Issue it again with a stronger key."
      }
    ],
    "severity": "high",
    "first_seen_at": "first_seen_at",
    "url": "https://server.chief.app/team/acme/certificates/01j8q8zk2f4m6n7p9r1s3t5v7x"
  }
}

json

application/json

Sites Applications