//mTLS Certificate Authority

mTLS Certificate Authority

Per-organization private Certificate Authority (CA) for issuing mutual TLS client certificates.

All endpoints require Authorization: Bearer <admin-jwt> with the admin scope.

CA Lifecycle

POST /api/admin/organizations/:org_uuid/mtls-ca

Provisions a new private CA for the organization. Each organization can have at most one active CA.

Input: ~~~json { "common_name": "Acme Corp Internal CA", "key_algorithm": "rsa4096", "validity_days": 3650 } ~~~

Output: ~~~json { "ca_uuid": "ca-uuid-123", "common_name": "Acme Corp Internal CA", "certificate": "-----BEGIN CERTIFICATE----- ...", "expires_at": "2034-07-11T00:00:00Z" } ~~~

GET /api/admin/organizations/:org_uuid/mtls-ca

Returns the organization's CA certificate (PEM format).

DELETE /api/admin/organizations/:org_uuid/mtls-ca

Revokes and deletes the CA. All certificates issued by this CA are immediately invalidated.

Certificate Issuance

POST /api/admin/organizations/:org_uuid/mtls-ca/certificates

Issues a client certificate signed by the organization's CA.

Input: ~~~json { "common_name": "service-worker-1", "sans": ["service-worker-1.internal.acme.com"], "validity_days": 90, "metadata": { "service": "worker", "environment": "production" } } ~~~

Output: ~~~json { "cert_uuid": "cert-uuid-456", "certificate": "-----BEGIN CERTIFICATE----- ...", "private_key": "-----BEGIN PRIVATE KEY----- ...", "expires_at": "2024-10-09T00:00:00Z" } ~~~

The private key is returned once only at issuance time. Store it securely.

GET /api/admin/organizations/:org_uuid/mtls-ca/certificates

Lists all issued certificates (without private keys).

DELETE /api/admin/organizations/:org_uuid/mtls-ca/certificates/:cert_uuid

Revokes a certificate immediately. The certificate is added to the organization's CRL.

CRL (Certificate Revocation List)

GET /api/organizations/:org_uuid/mtls-ca/crl.pem

Returns the current Certificate Revocation List in PEM format.

OCSP

POST /api/organizations/:org_uuid/mtls-ca/ocsp

Online Certificate Status Protocol endpoint for real-time certificate status checks.

Endpoint Summary

| Method | Path | Purpose | |---|---|---| | POST | /api/admin/organizations/{org}/mtls-ca | Provision CA | | GET | /api/admin/organizations/{org}/mtls-ca | Get CA certificate | | DELETE | /api/admin/organizations/{org}/mtls-ca | Revoke CA | | POST | /api/admin/organizations/{org}/mtls-ca/certificates | Issue certificate | | GET | /api/admin/organizations/{org}/mtls-ca/certificates | List certificates | | DELETE | /api/admin/organizations/{org}/mtls-ca/certificates/{uuid} | Revoke certificate | | GET | /api/organizations/{org}/mtls-ca/crl.pem | CRL |

When to Use

  • Service-to-service authentication within your infrastructure
  • Signing client certs for partner integrations without exposing your prod CA

Error Reference

| Status | Code | Meaning | |--------|------|---------| | 400 | invalid_csr | Certificate Signing Request is malformed | | 400 | invalid_san | Subject Alternative Name not allowed | | 401 | unauthorized | Missing or invalid Authorization header | | 403 | forbidden | Admin scope required | | 404 | ca_not_found | CA for this org does not exist — provision one first | | 409 | cert_exists | Certificate with this CN already active | | 422 | expired_csr | CSR validity window has passed |