Certificates API¶

Certificate Lifecycle Management — Request, Issue, Revoke, Renew, Import/Export

Document Version: 1.1.0
Last Updated: 2026-04-04

Endpoints Overview¶

Method	Endpoint	Description
POST	`/api/v1/certificates/csr`	Submit Certificate Signing Request
GET	`/api/v1/certificates`	List certificates
GET	`/api/v1/certificates/:id`	Get certificate details
PUT	`/api/v1/certificates/:id`	Update certificate properties
POST	`/api/v1/certificates/:id/approve`	Approve pending CSR
POST	`/api/v1/certificates/:id/reject`	Reject pending CSR
POST	`/api/v1/certificates/:id/revoke`	Revoke certificate
POST	`/api/v1/certificates/:id/unrevoke`	Unrevoke certificate
GET	`/api/v1/certificates/:id/export`	Export certificate
POST	`/api/v1/certificates/import`	Import certificate
POST	`/api/v1/certificates/import/bulk`	Bulk import (PEM bundle)
POST	`/api/v1/certificates/import/file`	Import from file upload
POST	`/api/v1/certificates/import/preview`	Preview import before committing
GET	`/api/v1/certificates/:id/status`	Get revocation status
POST	`/api/v1/certificates/:id/archive`	Archive certificate
POST	`/api/v1/certificates/:id/restore`	Restore archived certificate
DELETE	`/api/v1/certificates/:id/permanent`	Permanently delete certificate
POST	`/api/v1/certificates/:id/renew`	Trigger certificate renewal
GET	`/api/v1/certificates/:id/renewal-history`	Get renewal history
GET	`/api/v1/certificates/:id/rotation/config`	Get rotation config
PUT	`/api/v1/certificates/:id/rotation/config`	Update rotation config
POST	`/api/v1/certificates/:id/rotation/trigger`	Trigger rotation
GET	`/api/v1/certificates/:id/rotation/history`	Rotation execution history
POST	`/api/v1/certificates/:id/targets`	Create rotation target
GET	`/api/v1/certificates/:id/targets`	List rotation targets
GET	`/api/v1/ca/:id/crl`	Download CRL (per CA)
POST	`/api/v1/ca/:id/crl/regenerate`	Force CRL regeneration (per CA)

Submit CSR¶

The CSR endpoint accepts a PEM-encoded Certificate Signing Request. The client generates the CSR (including subject fields and SANs) locally, and submits only the encoded CSR with a template reference.

POST /api/v1/certificates/csr HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "csr_pem": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
  "template_id": "550e8400-e29b-41d4-a716-446655440010",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "requested_cn": "api.example.com"
}

Request Fields¶

Field	Type	Required	Description
`csr_pem`	string	✅	PEM-encoded Certificate Signing Request
`template_id`	string	✅	Certificate template ID (UUID)
`project_id`	string	—	Project identifier (UUID)
`requested_cn`	string	—	Requested Common Name (for display/audit)
`agent_id`	string	—	Agent ID if submitted by an agent (UUID)

Generating a CSR

Use openssl req -new -key private.key -out request.csr or the MazeVault CLI to generate a CSR locally. Subject fields (CN, O, OU, C, ST, L) and SANs are embedded in the CSR itself.

Response `201 Created`¶

{
  "id": "cert_def456",
  "common_name": "api.example.com",
  "status": "pending_approval",
  "serial_number": "01:AB:CD:EF:12:34",
  "ca_id": "ca_root001",
  "project_id": "proj_abc123",
  "requested_at": "2026-02-10T14:30:00Z",
  "requested_by": "usr_abc123"
}

List Certificates¶

GET /api/v1/certificates?project_id=proj_abc123&status=active&page=1 HTTP/1.1
Authorization: Bearer <token>

Query Parameters¶

Parameter	Type	Description
`project_id`	string	Filter by project
`status`	string	Filter: `active`, `pending_approval`, `revoked`, `expired`
`ca_id`	string	Filter by issuing CA
`common_name`	string	Search by CN (substring match)
`expiring_within_days`	integer	Certificates expiring within N days
`page`	integer	Page number
`per_page`	integer	Items per page (max: 100)

Response `200 OK`¶

{
  "data": [
    {
      "id": "cert_def456",
      "common_name": "api.example.com",
      "serial_number": "01:AB:CD:EF:12:34",
      "status": "active",
      "issuer_cn": "MazeVault Internal CA",
      "not_before": "2026-02-10T00:00:00Z",
      "not_after": "2027-02-10T00:00:00Z",
      "key_type": "RSA-2048",
      "san": ["api.example.com", "api-internal.example.com"],
      "project_id": "proj_abc123"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}

Revoke Certificate¶

POST /api/v1/certificates/cert_def456/revoke HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "reason": "keyCompromise",
  "comment": "Private key exposed in security incident"
}

Revocation Reason Codes (RFC 5280)¶

Code	Reason	Description
0	`unspecified`	No specific reason
1	`keyCompromise`	Private key compromised
2	`caCompromise`	CA private key compromised
3	`affiliationChanged`	Subject's affiliation changed
4	`superseded`	Certificate replaced by new one
5	`cessationOfOperation`	Subject no longer operates
6	`certificateHold`	Temporary hold (reversible)

Response `200 OK`¶

{
  "id": "cert_def456",
  "status": "revoked",
  "revocation_reason": "keyCompromise",
  "revoked_at": "2026-02-10T15:00:00Z",
  "revoked_by": "usr_abc123"
}

Import Certificate¶

Single Import¶

POST /api/v1/certificates/import HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "certificate_pem": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----",
  "private_key_pem": "***REMOVED***",
  "chain_pem": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----",
  "project_id": "proj_abc123"
}

Field	Type	Required	Description
`certificate_pem`	string	✅	PEM-encoded certificate
`private_key_pem`	string	—	PEM-encoded private key
`chain_pem`	string	—	PEM-encoded CA chain
`project_id`	string	✅	Target project

Bulk Import (PEM Bundle)¶

POST /api/v1/certificates/import/bulk HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "pem_bundle": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "project_id": "proj_abc123"
}

Export Certificate¶

GET /api/v1/certificates/cert_def456/export?format=pem HTTP/1.1
Authorization: Bearer <token>

Query Parameters¶

Parameter	Values	Description
`format`	`pem`, `der`, `pkcs12`	Export format
`include_chain`	`true`, `false`	Include CA chain (default: true)
`include_key`	`true`, `false`	Include private key (default: false)
`password`	string	PKCS#12 export password (required for pkcs12)

Audit

Certificate exports that include the private key are recorded as high-severity audit events.

ACME Protocol Endpoints¶

MazeVault exposes a full ACME server (RFC 8555) for automated certificate management. These endpoints are used by ACME clients such as cert-manager.

ACME Endpoints Overview¶

Method	Endpoint	Description
GET	`/api/acme/directory`	ACME directory (discovery)
HEAD	`/api/acme/new-nonce`	Get replay-protection nonce
POST	`/api/acme/new-nonce`	Get replay-protection nonce
POST	`/api/acme/new-account`	Register new account (EAB required)
POST	`/api/acme/new-order`	Create certificate order
POST	`/api/acme/order/:id`	Get order status
POST	`/api/acme/authz/:id`	Get authorization details
POST	`/api/acme/challenge/:id`	Trigger challenge validation
POST	`/api/acme/finalize/:id`	Submit CSR for signing
POST	`/api/acme/cert/:id`	Download issued certificate

ACME Directory¶

GET /api/acme/directory HTTP/1.1

Response 200 OK:

{
  "newNonce": "https://vault.example.com/api/acme/new-nonce",
  "newAccount": "https://vault.example.com/api/acme/new-account",
  "newOrder": "https://vault.example.com/api/acme/new-order",
  "revokeCert": "https://vault.example.com/api/acme/revoke-cert",
  "keyChange": "https://vault.example.com/api/acme/key-change",
  "meta": {
    "externalAccountRequired": true,
    "profiles": {
      "web-server": { "description": "Template: Web Server TLS" },
      "client-auth": { "description": "Template: Client Authentication" }
    }
  }
}

EAB Credential Management¶

Method	Endpoint	Permission	Description
POST	`/api/v1/organizations/:id/acme-credentials`	`ca:write`	Create EAB credential
GET	`/api/v1/organizations/:id/acme-credentials`	`ca:read`	List EAB credentials
DELETE	`/api/v1/organizations/:id/acme-credentials/:credId`	`ca:write`	Revoke EAB credential

Create EAB Credential¶

POST /api/v1/organizations/{org_id}/acme-credentials HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "project_id": "proj_abc123",
  "default_template_id": "tmpl_def456",
  "cluster_label": "prod-aks-westeurope"
}

Response 201 Created:

{
  "id": "cred_xyz789",
  "eab_key_id": "***REMOVED***",
  "eab_hmac_key": "***REMOVED***",
  "cluster_label": "prod-aks-westeurope",
  "created_at": "2026-03-14T10:00:00Z"
}

One-time HMAC Key

The eab_hmac_key is returned only at creation. Store it securely — it cannot be retrieved later.

For detailed ACME setup with cert-manager and Kubernetes YAML examples, see the ACME Certificate Automation Guide.

CRL Distribution¶

CRL endpoints are per CA. Each CA has its own CRL distribution point.

Download CRL¶

GET /api/v1/ca/ca_root001/crl HTTP/1.1
Accept: application/pkix-crl

Returns DER-encoded CRL for the specified CA.

Force CRL Regeneration¶

POST /api/v1/ca/ca_root001/crl/regenerate HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "full"
}

Field	Values	Description
`type`	`full`, `delta`	Full CRL or delta CRL

SCEP Endpoint¶

GET /api/v1/scep/:ca_id HTTP/1.1

SCEP operations follow RFC 8894. Supports GetCACaps, GetCACert, PKIOperation.

Required Permissions¶

Operation	Required Permission
Submit CSR	`certificate:request`
List/View Certificates	`certificate:read`
Approve/Reject CSR	`certificate:approve`
Revoke Certificate	`certificate:revoke`
Import Certificate	`certificate:import`
Export Certificate	`certificate:read`
Archive / Restore	`certificate:archive`
Permanent Delete	`certificate:permanent_delete`
Manage Rotation Config	`rotation:write`
Trigger Rotation	`rotation:execute`
Trigger Renewal	`certificate:write`
Manage CRL	`ca:admin`

Certificate Archive & Lifecycle¶

Archive Certificate¶

POST /api/v1/certificates/cert_def456/archive HTTP/1.1
Authorization: Bearer <token>

Moves the certificate to the archive.

Restore Certificate¶

POST /api/v1/certificates/cert_def456/restore HTTP/1.1
Authorization: Bearer <token>

Permanent Delete¶

DELETE /api/v1/certificates/cert_def456/permanent HTTP/1.1
Authorization: Bearer <token>

Irreversible

Permanent deletion removes the certificate and all associated data.

Certificate Rotation¶

Automate certificate rotation to external targets (secret managers, load balancers, cloud services).

Get Rotation Config¶

GET /api/v1/certificates/cert_def456/rotation/config HTTP/1.1
Authorization: Bearer <token>

Update Rotation Config¶

PUT /api/v1/certificates/cert_def456/rotation/config HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Trigger Rotation¶

POST /api/v1/certificates/cert_def456/rotation/trigger HTTP/1.1
Authorization: Bearer <token>

Rotation History¶

GET /api/v1/certificates/cert_def456/rotation/history HTTP/1.1
Authorization: Bearer <token>

Manage Rotation Targets¶

Method	Endpoint	Description
POST	`/api/v1/certificates/:id/targets`	Create rotation target
GET	`/api/v1/certificates/:id/targets`	List rotation targets
GET	`/api/v1/certificates/:id/targets/:targetId`	Get target details
PUT	`/api/v1/certificates/:id/targets/:targetId`	Update target
DELETE	`/api/v1/certificates/:id/targets/:targetId`	Delete target
POST	`/api/v1/certificates/:id/targets/:targetId/sync`	Sync target manually

Certificate Renewal¶

Trigger Renewal¶

POST /api/v1/certificates/cert_def456/renew HTTP/1.1
Authorization: Bearer <token>

Renewal History¶

GET /api/v1/certificates/cert_def456/renewal-history HTTP/1.1
Authorization: Bearer <token>

Renewal Queue¶

Method	Endpoint	Description
GET	`/api/v1/renewal-queue`	List certificates pending renewal
POST	`/api/v1/renewal-queue/:id/approve`	Approve renewal
POST	`/api/v1/renewal-queue/:id/cancel`	Cancel renewal

Import Preview¶

Preview certificate imports before committing:

POST /api/v1/certificates/import/preview HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Returns parsed certificate details without importing.

File Upload Import¶

POST /api/v1/certificates/import/file HTTP/1.1
Authorization: Bearer <token>
Content-Type: multipart/form-data

Accepts certificate files (PEM, DER, PFX/PKCS#12) via multipart upload.

Getting Started — Authentication and API basics
Certificate Management Guide — UI-based certificate operations
TLS Configuration — TLS deployment setup

Certificates API¶

Endpoints Overview¶

Submit CSR¶

Request Fields¶

Response 201 Created¶

List Certificates¶

Query Parameters¶

Response 200 OK¶

Revoke Certificate¶

Revocation Reason Codes (RFC 5280)¶

Response 200 OK¶

Import Certificate¶

Single Import¶

Bulk Import (PEM Bundle)¶

Export Certificate¶

Query Parameters¶

ACME Protocol Endpoints¶

ACME Endpoints Overview¶

ACME Directory¶

EAB Credential Management¶

Create EAB Credential¶

CRL Distribution¶

Download CRL¶

Force CRL Regeneration¶

SCEP Endpoint¶

Required Permissions¶

Certificate Archive & Lifecycle¶

Archive Certificate¶

Restore Certificate¶

Permanent Delete¶

Certificate Rotation¶

Get Rotation Config¶

Update Rotation Config¶

Trigger Rotation¶

Rotation History¶

Manage Rotation Targets¶

Certificate Renewal¶

Trigger Renewal¶

Renewal History¶

Renewal Queue¶

Import Preview¶

File Upload Import¶

Related¶

Response `201 Created`¶

Response `200 OK`¶

Response `200 OK`¶