Get expiring certificates

GET

/api/v1/certificates/expiring

const url = 'http://localhost:3000/api/v1/certificates/expiring?days=30&page=1&limit=20';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://localhost:3000/api/v1/certificates/expiring?days=30&page=1&limit=20' \
  --header 'X-API-Key: <X-API-Key>'

Retrieves certificates that are expiring within a specified number of days.

Authorizations

api-key
bearer

Parameters

Query Parameters

days

number

default: 30 >= 1 <= 365

Example

Number of days to look ahead for expiring certificates

page

number

default: 1 >= 1

Page number (1-based)

limit

number

default: 20 >= 1 <= 100

Number of items per page

Header Parameters

x-organization-id

string format: uuid

UUID of the organization (tenant) the request acts in. It selects the tenant and grants nothing: the server checks membership or an open tenant switch. Not needed for global operations. A malformed value returns 400. API keys are fixed to their own organization; another organization returns 403. The x-organization-source header grants nothing.

Responses

200

Expiring certificates retrieved successfully

application/json

object

data

required

List of certificates

Array<object>

object

required

Certificate UUID

string

type

required

Certificate type

string

Allowed values: device ca

subject

required

Certificate subject (Common Name)

string

issuer

required

Certificate issuer

string

fingerprint

required

Certificate SHA-256 fingerprint

string

notBefore

required

Certificate validity start date

string format: date-time

notAfter

required

Certificate expiration date

string format: date-time

status

required

Certificate status

string

Allowed values: valid expiring expired revoked unknown

validityKnown

required

False for a legacy device certificate whose notBefore, notAfter and issuer were not read from a certificate. Its dates are placeholders and must not be shown or alerted on.

boolean

deviceId

Device ID (only for device certificates)

string

deviceName

Device name (only for device certificates)

string

createdAt

required

Certificate creation date

string format: date-time

serialNumber

Certificate serial number (hex)

string

keyAlgorithm

Public key algorithm and size

string

signatureAlgorithm

Signature algorithm

string

subjectAltNames

Subject Alternative Names

Array<string>

certificate

PEM-encoded public certificate (CA certs only)

string

total

required

Total number of certificates matching the filter

number

page

required

Current page number

number

limit

required

Number of items per page

number

totalPages

required

Total number of pages

number

Example

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "device",
      "subject": "CN=device-001.example.com",
      "issuer": "CN=Margo Root CA",
      "fingerprint": "A1:B2:C3:D4:E5:F6...",
      "notBefore": "2024-01-01T00:00:00.000Z",
      "notAfter": "2025-01-01T00:00:00.000Z",
      "status": "valid",
      "validityKnown": true,
      "deviceId": "550e8400-e29b-41d4-a716-446655440001",
      "deviceName": "Production Gateway 1",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 20,
  "totalPages": 8
}

401

Unauthorized - Invalid or missing authentication

403

Forbidden - Insufficient permissions