API-Zugang

Automatisieren Sie die Zertifikatsverwaltung mit der REST-API. Die API unterstützt zwei Authentifizierungsmethoden: OAuth 2.1 und API-Schlüssel, beide mit granularen Berechtigungen pro CA.

Authentifizierung mit OAuth

Die API unterstützt OAuth 2.1 mit PKCE (S256). Sobald Sie ein Zugriffstoken haben, fügen Sie es in den Authorization-Header ein:

Authorization: Bearer cm_oauth_xxxxxxxxxxxx

OAuth-Client erstellen

Für serverseitige Anwendungen erstellen Sie einen vertraulichen OAuth-Client im Dashboard unter OAuth-Clients. Sie erhalten eine client_id und ein client_secret. Öffentliche Clients (z. B. SPAs, CLI-Tools) können stattdessen die Dynamic Client Registration verwenden — es wird kein Secret ausgestellt, aber PKCE ist erforderlich.

OAuth-Endpunkte

Endpunkt	URL
Autorisierung	`https://certman.app/oauth/authorize`
Token	`https://certman.app/oauth/token`
Widerruf	`https://certman.app/oauth/revoke`
Dynamische Registrierung	`https://certman.app/oauth/register`

Autorisierungsablauf

Leiten Sie den Benutzer zum Autorisierungsendpunkt weiter mit response_type=code, Ihrer client_id, einer redirect_uri, PKCE code_challenge und resource=https://api.certman.app
Der Benutzer wählt einen Workspace aus und erteilt Berechtigungen pro CA (Lesen, Ausstellen, Widerrufen)
Tauschen Sie den erhaltenen Autorisierungscode am Token-Endpunkt gegen ein Zugriffstoken ein
Vertrauliche Clients authentifizieren sich mit client_secret_post; öffentliche Clients verwenden nur PKCE

Token-Aktualisierung

Zugriffstoken laufen nach 1 Stunde ab. Verwenden Sie den refresh_token-Grant am Token-Endpunkt, um ein neues Zugriffstoken ohne Benutzerinteraktion zu erhalten. Refresh-Tokens sind 30 Tage gültig und rotieren bei jeder Verwendung — speichern Sie immer das neue Refresh-Token aus der Antwort.

Authentifizierung mit API-Schlüssel

Navigieren Sie zu API / MCP-Zugang in der Seitenleiste, um Schlüssel zu erstellen. API-Schlüssel müssen auf bestimmte CAs beschränkt sein — sie haben keinen workspace-weiten Zugriff. Jedem Schlüssel können spezifische Berechtigungen pro CA gewährt werden:

Lesen — CA- und Zertifikatsdetails anzeigen
Ausstellen — Neue Zertifikate erstellen
Widerrufen — Bestehende Zertifikate widerrufen

Im Free-Plan erhalten API-Schlüssel vollen Zugriff (alle drei Berechtigungen) auf ausgewählte CAs. Der Pro-Plan ermöglicht granulare Kontrolle — zum Beispiel nur Lesezugriff auf eine CA und Lesen+Ausstellen für eine andere.

Fügen Sie Ihren API-Schlüssel in den Authorization-Header ein:

Authorization: Bearer cm_xxxxxxxxxxxx

Basis-URL

Alle API-Endpunkte sind verfügbar unter https://api.certman.app

OpenAPI-Spezifikation

Die vollständige API-Spezifikation ist im OpenAPI 3.0-Format verfügbar unter https://api.certman.app/v1/openapi. Sie können diese mit Tools wie Swagger Editor, Postman oder jedem OpenAPI-kompatiblen Client verwenden, um die API zu erkunden und zu testen.

Rate Limits

API-Anfragen sind rate-limitiert, um faire Nutzung zu gewährleisten. Zertifikatsausstellungs- und Erneuerungsoperationen haben ein niedrigeres Limit aufgrund ihrer Rechenkosten. Wenn Sie das Rate Limit überschreiten, erhalten Sie eine 429-Antwort.

Fehlerformat

Alle Fehlerantworten folgen einem einheitlichen Format:

{ "error": "Menschenlesbare Fehlermeldung" }

Häufige HTTP-Statuscodes:

400 — Ungültige Anfrage (ungültige Parameter)
401 — Nicht autorisiert (fehlende oder ungültige Anmeldedaten)
403 — Verboten (unzureichende Berechtigungen)
404 — Nicht gefunden
429 — Zu viele Anfragen (Rate Limit erreicht)
500 — Interner Serverfehler

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.