Přístup k API

Automatizujte správu certifikátů pomocí REST API. API podporuje dva způsoby autentizace: OAuth 2.1 a API klíče, oba s granulárními oprávněními pro každou CA.

Autentizace pomocí OAuth

API podporuje OAuth 2.1 s PKCE (S256). Jakmile máte přístupový token, zahrňte jej do hlavičky Authorization:

Authorization: Bearer cm_oauth_xxxxxxxxxxxx

Vytvoření OAuth klienta

Pro serverové aplikace vytvořte důvěrného OAuth klienta v dashboardu v sekci OAuth klienti. Obdržíte client_id a client_secret. Veřejní klienti (např. SPA, CLI nástroje) mohou použít Dynamic Client Registration — secret se nevydává, ale PKCE je vyžadováno.

OAuth endpointy

Endpoint	URL
Autorizace	`https://certman.app/oauth/authorize`
Token	`https://certman.app/oauth/token`
Odvolání	`https://certman.app/oauth/revoke`
Dynamická registrace	`https://certman.app/oauth/register`

Autorizační tok

Přesměrujte uživatele na autorizační endpoint s response_type=code, vaší client_id, redirect_uri, PKCE code_challenge a resource=https://api.certman.app
Uživatel vybere workspace a udělí oprávnění pro jednotlivé CA (čtení, vydávání, odvolání)
Vyměňte získaný autorizační kód za přístupový token na token endpointu
Důvěrní klienti se autentizují pomocí client_secret_post; veřejní klienti používají pouze PKCE

Obnovení tokenu

Přístupové tokeny vyprší po 1 hodině. Použijte grant refresh_token na token endpointu k získání nového přístupového tokenu bez interakce uživatele. Refresh tokeny jsou platné 30 dní a rotují při každém použití — vždy uložte nový refresh token z odpovědi.

Autentizace pomocí API klíče

Přejděte na API / MCP přístup v postranním panelu pro vytvoření klíčů. API klíče musí být omezeny na konkrétní CA — nemají přístup k celému workspace. Každému klíči mohou být udělena specifická oprávnění pro každou CA:

Čtení — Zobrazení detailů CA a certifikátů
Vydávání — Vytváření nových certifikátů
Odvolání — Odvolání existujících certifikátů

Na Free plánu mají API klíče plný přístup (všechna tři oprávnění) k vybraným CA. Pro plán umožňuje granulární kontrolu — například pouze čtení pro jednu CA a čtení+vydávání pro jinou.

Zahrňte svůj API klíč do hlavičky Authorization:

Authorization: Bearer cm_xxxxxxxxxxxx

Základní URL

Všechny API endpointy jsou dostupné na https://api.certman.app

OpenAPI specifikace

Kompletní API specifikace je dostupná ve formátu OpenAPI 3.0 na https://api.certman.app/v1/openapi. Můžete ji použít s nástroji jako Swagger Editor, Postman nebo jakýmkoli OpenAPI kompatibilním klientem pro prozkoumání a testování API.

Rate limity

API požadavky jsou omezeny rate limity pro zajištění spravedlivého použití. Operace vydávání a obnovování certifikátů mají nižší limit kvůli jejich výpočetním nárokům. Pokud překročíte rate limit, obdržíte odpověď 429.

Formát chyb

Všechny chybové odpovědi následují konzistentní formát:

{ "error": "Lidsky čitelná chybová zpráva" }

Běžné HTTP stavové kódy:

400 — Chybný požadavek (neplatné parametry)
401 — Neautorizováno (chybějící nebo neplatné přihlašovací údaje)
403 — Zakázáno (nedostatečná oprávnění)
404 — Nenalezeno
429 — Příliš mnoho požadavků (rate limit dosažen)
500 — Interní chyba serveru

Endpoints

GET /v1/whoami Get current identity

Returns information about the authenticated API key, including the associated user, workspace, and permissions.

Example Request

curl https://api.certman.app/v1/whoami \
  -H "Authorization: Bearer cm_xxxxxxxxxxxx"

Response

200 OK

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com"
  },
  "workspace": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "My Workspace",
    "slug": "my-workspace"
  },
  "apiKey": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "name": "Production Key",
    "prefix": "cm_prod"
  },
  "permissions": {
    "880e8400-e29b-41d4-a716-446655440003": {
      "canRead": true,
      "canIssue": true,
      "canRevoke": false
    }
  }
}

GET /v1/cas List Certificate Authorities

Returns a list of all Certificate Authorities that the API key has read access to. Revoked CAs are automatically excluded.

Query Parameters

Parameter	Type	Required	Description
`parentCaId`	string	No	Filter by parent CA ID. Use to list only children of a specific CA.
`type`	string	No	`root` \| `intermediate` \| `all` (default: all)

Example Request

curl https://api.certman.app/v1/cas \
  -H "Authorization: Bearer cm_xxxxxxxxxxxx"

Response

200 OK

{
  "cas": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production Root CA",
      "common_name": "Production Root CA",
      "organization": "Acme Corp",
      "key_algorithm": "ECDSA-P384",
      "valid_from": "2024-01-01T00:00:00.000Z",
      "valid_to": "2034-01-01T00:00:00.000Z",
      "created_at": "2024-01-01T00:00:00.000Z",
      "parent_ca_id": null,
      "depth": 0,
      "path_length": null
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Production Intermediate CA",
      "common_name": "Production Intermediate CA",
      "organization": "Acme Corp",
      "key_algorithm": "ECDSA-P256",
      "valid_from": "2024-06-01T00:00:00.000Z",
      "valid_to": "2029-06-01T00:00:00.000Z",
      "created_at": "2024-06-01T00:00:00.000Z",
      "parent_ca_id": "550e8400-e29b-41d4-a716-446655440000",
      "depth": 1,
      "path_length": 0
    }
  ]
}

GET /v1/cas/:id Get Certificate Authority details

Returns detailed information about a specific Certificate Authority, including its certificate PEM.

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	Certificate Authority ID

Example Request

curl https://api.certman.app/v1/cas/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer cm_xxxxxxxxxxxx"

Response

200 OK

{
  "ca": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Root CA",
    "common_name": "Production Root CA",
    "organization": "Acme Corp",
    "country": "US",
    "state": "California",
    "locality": "San Francisco",
    "key_algorithm": "ECDSA-P384",
    "certificate_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "serial_number": "01AB23CD45EF",
    "valid_from": "2024-01-01T00:00:00.000Z",
    "valid_to": "2034-01-01T00:00:00.000Z",
    "created_at": "2024-01-01T00:00:00.000Z",
    "has_passphrase": false,
    "parent_ca_id": null,
    "depth": 0,
    "path_length": null,
    "revoked_at": null,
    "revocation_reason": null
  }
}

GET /v1/cas/:id/chain Get CA certificate chain

Returns the full certificate chain for a CA, from the specified CA up to the root. Useful for building trust stores or verifying certificate chains.

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	Certificate Authority ID

Example Request

curl https://api.certman.app/v1/cas/550e8400-e29b-41d4-a716-446655440000/chain \
  -H "Authorization: Bearer cm_xxxxxxxxxxxx"

Response

200 OK

{
  "caId": "660e8400-e29b-41d4-a716-446655440001",
  "chainLength": 2,
  "chain": [
    "-----BEGIN CERTIFICATE-----\n(intermediate CA cert)\n-----END CERTIFICATE-----",
    "-----BEGIN CERTIFICATE-----\n(root CA cert)\n-----END CERTIFICATE-----"
  ]
}

GET /v1/certificates List certificates

Returns a paginated list of certificates with optional filtering. Only certificates from CAs that the API key has read access to are returned.

Query Parameters

Parameter	Type	Required	Description
`caId`	string	No	Filter by Certificate Authority ID
`status`	string	No	`active` \| `revoked` \| `all` (default: all)
`search`	string	No	Search by common name (case-insensitive partial match)
`createdFrom`	string	No	Filter certificates created on or after this date (ISO 8601)
`createdTo`	string	No	Filter certificates created on or before this date (ISO 8601)
`expiringInDays`	integer	No	Filter certificates expiring within N days
`page`	integer	No	Page number (1-indexed) (default: 1)
`pageSize`	integer	No	Number of items per page (default: 20)

Example Request

curl "https://api.certman.app/v1/certificates?status=active&pageSize=10" \
  -H "Authorization: Bearer cm_xxxxxxxxxxxx"

Response

200 OK

{
  "certificates": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "ca_id": "550e8400-e29b-41d4-a716-446655440000",
      "common_name": "api.example.com",
      "san_dns": [
        "api.example.com",
        "www.example.com"
      ],
      "san_ip": [
        "192.168.1.1"
      ],
      "key_algorithm": "ECDSA-P256",
      "valid_from": "2024-06-01T00:00:00.000Z",
      "valid_to": "2025-06-01T00:00:00.000Z",
      "serial_number": "AABBCCDD",
      "revoked_at": null,
      "revocation_reason": null,
      "created_at": "2024-06-01T00:00:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "pageSize": 20,
  "totalPages": 3
}

POST /v1/certificates Issue a new certificate

Issues a new certificate from a Certificate Authority. Supports two modes: 'managed' (Certman generates the key pair) or 'csr' (you provide a Certificate Signing Request).

Idempotency: For CSR mode only, you can provide an Idempotency-Key header to ensure the request is idempotent. If you retry a request with the same key and body, you'll receive the same response. Keys expire after 24 hours. Managed mode does not support idempotency because each request generates a unique private key.

Request Body

Parameter	Type	Required	Description
`caId`	string	Yes	ID of the Certificate Authority to issue from
`mode`	string	No	`managed` \| `csr` (default: managed)
`commonName`	string	Conditional	Common name for the certificate (required for managed mode)
`sanDns`	string[]	No	DNS Subject Alternative Names (supports wildcards like *.example.com)
`sanIp`	string[]	No	IP address Subject Alternative Names (IPv4 or IPv6)
`keyAlgorithm`	string	No	`RSA-2048` \| `RSA-4096` \| `ECDSA-P256` \| `ECDSA-P384`
`validityDays`	integer	No	Certificate validity in days (max 397 per CA/Browser Forum)
`csrPem`	string	Conditional	Certificate Signing Request in PEM format (required for csr mode)
`caPassphrase`	string	No	CA passphrase (required if the CA is passphrase-protected)

Example Request

curl -X POST https://api.certman.app/v1/certificates \
  -H "Authorization: Bearer cm_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "caId": "550e8400-e29b-41d4-a716-446655440000",
    "mode": "managed",
    "commonName": "api.example.com",
    "sanDns": [
      "api.example.com",
      "www.example.com"
    ],
    "sanIp": [
      "192.168.1.1"
    ],
    "keyAlgorithm": "ECDSA-P256",
    "validityDays": 365
  }'

Response

200 OK

{
  "certificate": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "common_name": "api.example.com",
    "certificate_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "san_dns": [
      "api.example.com",
      "www.example.com"
    ],
    "san_ip": [
      "192.168.1.1"
    ],
    "valid_from": "2024-06-01T00:00:00.000Z",
    "valid_to": "2025-06-01T00:00:00.000Z",
    "serial_number": "AABBCCDD",
    "created_at": "2024-06-01T00:00:00.000Z"
  },
  "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
}

Note: privateKey is only returned for managed certificates. Store it securely.

POST /v1/certificates/:id/revoke Revoke a certificate

Revokes a certificate. Revoked certificates are included in the CA's Certificate Revocation List (CRL) and will be reported as revoked via OCSP.

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	Certificate ID

Request Body (Optional)

Parameter	Type	Required	Description
`reason`	string	No	`unspecified` \| `keyCompromise` \| `caCompromise` \| `affiliationChanged` \| `superseded` \| `cessationOfOperation` \| `certificateHold` \| `privilegeWithdrawn` (default: unspecified)
`caPassphrase`	string	No	CA passphrase (required if the CA is passphrase-protected)

Example Request

curl -X POST https://api.certman.app/v1/certificates/550e8400-e29b-41d4-a716-446655440000/revoke \
  -H "Authorization: Bearer cm_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "keyCompromise"
  }'

Response

200 OK

{
  "message": "Certificate revoked successfully",
  "certificate": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "common_name": "api.example.com",
    "revoked_at": "2024-07-15T12:30:00.000Z",
    "revocation_reason": "keyCompromise"
  }
}

POST /v1/certificates/:id/renew Renew a certificate

Creates a new certificate with the same properties as an existing certificate. For managed certificates, a new key pair is generated. For CSR-based certificates, you must provide a new CSR.

Idempotency: When providing a CSR, you can use an Idempotency-Key header to ensure the request is idempotent. If you retry a request with the same key and body, you'll receive the same response. Keys expire after 24 hours. Managed renewals do not support idempotency because each request generates a unique private key.

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	Certificate ID

Request Body (Optional)

Parameter	Type	Required	Description
`validityDays`	integer	No	Certificate validity in days (max 397 per CA/Browser Forum)
`csrPem`	string	No	New CSR in PEM format (required when renewing a CSR-based certificate)
`caPassphrase`	string	No	CA passphrase (required if the CA is passphrase-protected)

Example Request

curl -X POST https://api.certman.app/v1/certificates/550e8400-e29b-41d4-a716-446655440000/renew \
  -H "Authorization: Bearer cm_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "validityDays": 365
  }'

Response

200 OK

{
  "message": "Certificate renewed successfully",
  "certificate": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "common_name": "api.example.com",
    "certificate_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "san_dns": [
      "api.example.com",
      "www.example.com"
    ],
    "san_ip": [
      "192.168.1.1"
    ],
    "valid_from": "2025-06-01T00:00:00.000Z",
    "valid_to": "2026-06-01T00:00:00.000Z",
    "serial_number": "EEFF0011",
    "created_at": "2025-06-01T00:00:00.000Z"
  },
  "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
}

Note: privateKey is only returned for managed certificates. Store it securely.