@certman/sdk

Official TypeScript SDK for Certman API. Certman is a modern, API-first Certificate Authority platform for managing internal TLS - built for homelabs, DevOps teams, and anyone who wants full control without complexity.

Installation

npm install @certman/sdk

Quick Start

import { createCertmanClient } from '@certman/sdk';

const certman = createCertmanClient({
  apiKey: 'cm_your_api_key',
});

// List your Certificate Authorities
const { cas } = await certman.cas.list();

// Issue a new certificate
const { certificate, privateKey } = await certman.certificates.issue({
  caId: cas[0].id,
  commonName: 'api.example.com',
  sanDns: ['api.example.com', 'www.example.com'],
  validityDays: 365,
});

console.log(certificate.certificate_pem);
console.log(privateKey);

API Reference

createCertmanClient(config)

Creates a new Certman client instance.

Option	Type	Default	Description
apiKey	string	required	Your Certman API key
baseUrl	string	https://api.certman.app	API base URL
maxRetries	number	3	Max retry attempts for failed requests

Methods

Identity

• client.whoami() - Get current identity and permissions

Certificate Authorities

• client.cas.list() - List all accessible CAs
• client.cas.get(id) - Get CA details

Certificates

• client.certificates.list(params?) - List certificates with filtering
• client.certificates.issue(data) - Issue a new certificate
• client.certificates.revoke(id, reason?) - Revoke a certificate
• client.certificates.renew(id, data?) - Renew a certificate

Error Handling

The SDK provides typed error classes for different error scenarios:

import {
  CertmanError,
  CertmanAuthenticationError,
  CertmanPermissionError,
  CertmanNotFoundError,
  CertmanValidationError,
  CertmanRateLimitError,
} from '@certman/sdk';

try {
  await certman.certificates.issue({
    caId: 'ca-123',
    commonName: 'example.com',
    validityDays: 365,
  });
} catch (error) {
  if (error instanceof CertmanAuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof CertmanPermissionError) {
    console.error('No permission to issue certificates for this CA');
  } else if (error instanceof CertmanValidationError) {
    console.error('Invalid request:', error.message);
  } else if (error instanceof CertmanNotFoundError) {
    console.error('Resource not found');
  } else if (error instanceof CertmanRateLimitError) {
    console.error('Rate limit exceeded, please retry later');
  }
}

TypeScript Support

This SDK is written in TypeScript and provides full type definitions. All API responses are fully typed:

import type { IssuedCertificate, CaDetails } from '@certman/sdk';

const { certificate }: { certificate: IssuedCertificate } = await certman.certificates.issue({
  caId: 'ca-123',
  commonName: 'example.com',
  validityDays: 365,
});

Automatic Retries

The SDK automatically retries failed requests with exponential backoff for:

• 408 Request Timeout
• 429 Too Many Requests
• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout

Configure the maximum number of retries:

const certman = createCertmanClient({
  apiKey: 'cm_your_api_key',
  maxRetries: 5, // default is 3
});

Requirements

• Node.js 18.0.0 or later
• A Certman API key (get one at certman.app)

License

MIT