Certificates API¶

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

Document Version: 1.2.0
Last Updated: 2026-05-30

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 supports three request modes:

uploaded_csr: the client uploads a PEM-encoded CSR.
mazevault_generated: MazeVault generates the private key and CSR from the selected template and request parameters.
azure_key_vault_generated: Azure Key Vault generates the key and pending CSR; MazeVault submits the signed certificate back to the same Key Vault certificate object after issuance.

Use the selected template as the source of truth for allowed subject fields, SAN types, key algorithm, key size, and approval behavior.

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

{
  "template_id": "550e8400-e29b-41d4-a716-446655440010",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "requested_cn": "api.example.com",
  "csr_source_mode": "mazevault_generated",
  "requested_san": {
    "dns_names": ["api.example.com", "api-internal.example.com"]
  },
  "requested_subject": {
    "common_name": "api.example.com",
    "organization": "Example Corp"
  },
  "requested_key_algorithm": "RSA",
  "requested_key_size": 2048,
  "key_storage_mode": "local"
}

Request Modes¶

`csr_source_mode`	What MazeVault expects	Additional fields
`uploaded_csr`	Existing CSR PEM uploaded by the client	`csr_pem`
`mazevault_generated`	MazeVault generates key + CSR	`requested_subject`, `requested_san`, optional `requested_key_algorithm`, optional `requested_key_size`, optional `key_storage_mode`, optional `key_integration_id`, optional `key_secret_path`, optional `key_secret_name`, optional `create_new_secret`
`azure_key_vault_generated`	Azure Key Vault generates key + pending CSR	`requested_subject`, `requested_san`, optional `requested_key_algorithm`, optional `requested_key_size`, `key_integration_id`, optional `generation_reference`

Request Fields¶

Field	Type	Required	Description
`template_id`	string	✅	Certificate template ID (UUID)
`project_id`	string	—	Project identifier (UUID)
`organization_id`	string	—	Organization identifier (UUID); used in organization-scoped request flows
`csr_source_mode`	string	—	Request mode: `uploaded_csr`, `mazevault_generated`, or `azure_key_vault_generated`
`csr_pem`	string	Required for `uploaded_csr`	PEM-encoded Certificate Signing Request
`requested_cn`	string	—	Requested Common Name (for display/audit)
`requested_san`	object	—	Additional SAN values grouped as `dns_names`, `ip_addresses`, `email_addresses`, and `uris`
`requested_subject`	object	—	Subject overrides and visible template-derived fields such as `common_name`, `organization`, `organizational_unit`, `locality`, `state`, `country`, and `email_address`
`requested_key_algorithm`	string	—	Requested key algorithm when generation is allowed by the template
`requested_key_size`	integer	—	Requested key size when generation is allowed by the template
`key_storage_mode`	string	—	Private key custody mode for MazeVault-generated requests: `local` or `external`
`key_integration_id`	string	Required for `azure_key_vault_generated`; optional for external MazeVault key storage	Secret manager integration used for Azure Key Vault or external private key storage
`key_secret_path`	string	—	Existing external secret/key path when MazeVault stores a generated private key outside its local database
`key_secret_name`	string	—	New secret name when MazeVault should create the destination secret/key
`create_new_secret`	boolean	—	Indicates whether MazeVault should create a new destination secret for the generated private key
`generation_reference`	string	—	Optional caller-supplied reference used when naming generated Azure Key Vault certificate operations
`agent_id`	string	—	Agent ID if submitted by an agent (UUID)

Generating a CSR

For uploaded_csr, generate the CSR externally with OpenSSL or your own tooling and upload the PEM.

For generated modes, provide requested_cn, optional requested_subject, and requested_san. MazeVault validates the request against the selected template before CSR creation.

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 Modes¶

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`¶