Policy Management API¶

Service Accounts with appropriate scope can manage and validate certificate policies via the REST API. All policy endpoints are prefixed /api/v1/service/policies and require a valid session token.

See Authentication for details on obtaining a session token.

List Policies¶

GET /api/v1/service/policies
Authorization: Bearer <token>
Required scope: read

Supports optional query parameters:

Parameter	Description
`enabled`	Filter by `true` or `false`
`page`	Pagination page (default: 1)
`per_page`	Items per page, max 100 (default: 25)

Results are ordered alphabetically by name.

Get a Policy¶

GET /api/v1/service/policies/{id}
Authorization: Bearer <token>
Required scope: read

Returns a single policy by its numeric ID.

Create a Policy¶

POST /api/v1/service/policies
Authorization: Bearer <token>
Required scope: write
Content-Type: application/json

Example request:

{
  "name": "Production Security Baseline",
  "description": "Comprehensive security policy for production certificates",
  "matching_criteria": {
    "action": "certificate.generate",
    "domains": ["prod.example.com", "*.prod.example.com"]
  },
  "rules": [
    {
      "action": "enforce_minimum_key_size",
      "fail": "hard",
      "values": { "minimum_bits": "3072" }
    },
    {
      "action": "enforce_max_validity",
      "fail": "hard",
      "values": { "max_days": "365" }
    },
    {
      "action": "disable_wildcard",
      "fail": "hard"
    }
  ],
  "is_enabled": true
}

matching_criteria.action must be certificate.generate or certificate.renew. matching_criteria.domains is a non-empty array of domain strings; wildcard patterns (e.g. *.prod.example.com) are supported.

Update a Policy¶

PUT /api/v1/service/policies/{id}
Authorization: Bearer <token>
Required scope: write
Content-Type: application/json

Full replacement — all fields must be provided. Omitted fields are not preserved. Use the same request body structure as Create.

Enable / Disable a Policy¶

POST /api/v1/service/policies/{id}/enable
POST /api/v1/service/policies/{id}/disable
Authorization: Bearer <token>
Required scope: write

Both endpoints are idempotent and return the current policy state even if it was already in the requested state.

Delete a Policy¶

DELETE /api/v1/service/policies/{id}
Authorization: Bearer <token>
Required scope: write

Permanently deletes the policy. There is no soft-delete or recovery mechanism.

Validate a Certificate Request Against Policies¶

POST /api/v1/service/policies/validate
Authorization: Bearer <token>
Required scope: read
Content-Type: application/json

Simulates policy evaluation for a proposed certificate request without issuing any certificate. This is the primary integration point for CI/CD pipelines that want to pre-validate a request before invoking issuance.

Example request:

{
  "common_name": "api.prod.example.com",
  "subject_alternative_names": ["www.prod.example.com"],
  "organization": "Example Corp",
  "country": "US",
  "algorithm": "rsa-2048",
  "digest": "sha256",
  "validity_days": 365,
  "key_usage": ["digitalSignature", "keyEncipherment"],
  "extended_key_usage": ["serverAuth"]
}

Example response:

{
  "success": true,
  "overall_result": "fail",
  "summary": {
    "policies_evaluated": 1,
    "hard_failures": 1,
    "warnings": 0
  },
  "hard_failures": [
    {
      "policy": "Production Security Baseline",
      "field": "algorithm",
      "message": "RSA key size 2048 bits is below minimum required 3072 bits"
    }
  ],
  "warnings": []
}

overall_result is "pass" when there are no hard failures, and "fail" if any hard failure exists. Soft-fail rule violations appear as warnings and do not affect overall_result.

Audit Logging¶

All policy operations performed via Service Account are recorded in the platform audit log:

Event	Trigger
`policy.created`	Policy created via API
`policy.updated`	Policy updated via API (includes old and new values)
`policy.enabled` / `policy.disabled`	Policy enable/disable state changed
`policy.deleted`	Policy deleted via API
`policy.validated`	Certificate request validated against policies