Governance

Manage governance policies, compliance solutions, attestations, and policy templates. Enforce organizational standards, track compliance scores, and maintain audit trails across all managed resources.

All endpoints require a valid API key with the appropriate governance:* scope.

Base URL: https://<your-instance>/api/v1

---

Policy Object

{
  "id": "pol_abc123",
  "name": "Data Encryption at Rest",
  "description": "Ensures all persistent storage volumes use AES-256 encryption",
  "status": "active",
  "category": "security",
  "severity": "high",
  "rules": [
    {
      "field": "encryption.enabled",
      "operator": "equals",
      "value": true
    }
  ],
  "organizationId": "org_xyz789",
  "isActive": true,
  "createdAt": "2025-03-01T10:00:00Z",
  "updatedAt": "2025-03-15T14:30:00Z"
}

PolicyInstance Object

{
  "id": "pinst_def456",
  "policyId": "pol_abc123",
  "resourceId": "addon_ghi789",
  "resourceType": "addon",
  "status": "approved",
  "result": {
    "compliant": true,
    "checks": 5,
    "passed": 5,
    "failed": 0
  },
  "submittedAt": "2025-03-10T09:00:00Z",
  "reviewedAt": "2025-03-10T11:00:00Z",
  "reviewedBy": "user_002",
  "comments": [
    {
      "userId": "user_002",
      "comment": "All encryption checks passed.",
      "createdAt": "2025-03-10T11:00:00Z"
    }
  ],
  "createdAt": "2025-03-10T08:00:00Z",
  "updatedAt": "2025-03-10T11:00:00Z"
}

Solution Object

{
  "id": "sol_jkl012",
  "name": "Customer Data Platform",
  "description": "End-to-end solution for customer data management",
  "status": "compliant",
  "organizationId": "org_xyz789",
  "ownership": {
    "team": "data-engineering",
    "owner": "user_001"
  },
  "policies": ["pol_abc123", "pol_mno345"],
  "models": ["model_pqr678"],
  "complianceScore": 94.5,
  "createdAt": "2025-02-15T08:00:00Z",
  "updatedAt": "2025-03-20T16:00:00Z"
}

ComplianceSnapshot Object

{
  "id": "snap_stu901",
  "solutionId": "sol_jkl012",
  "snapshotType": "scheduled",
  "frozen": false,
  "score": 94.5,
  "totalPolicies": 12,
  "compliantPolicies": 11,
  "nonCompliantPolicies": 1,
  "approvedAt": null,
  "approvedBy": null,
  "createdAt": "2025-03-20T00:00:00Z",
  "updatedAt": "2025-03-20T00:00:00Z"
}

Attestation Object

{
  "id": "att_vwx234",
  "solutionId": "sol_jkl012",
  "snapshotId": "snap_stu901",
  "type": "soc2",
  "status": "active",
  "attestedBy": "user_001",
  "attestedAt": "2025-03-21T10:00:00Z",
  "evidence": {
    "documentUrl": "https://example.com/evidence/soc2-report.pdf",
    "notes": "Annual SOC 2 Type II audit completed"
  },
  "expiration": "2026-03-21T10:00:00Z",
  "revokedAt": null,
  "revokedBy": null,
  "createdAt": "2025-03-21T10:00:00Z",
  "updatedAt": "2025-03-21T10:00:00Z"
}

PolicyTemplate Object

{
  "id": "tmpl_yza567",
  "name": "HIPAA Data Protection",
  "description": "Pre-built policy template for HIPAA data protection compliance",
  "category": "healthcare",
  "policyDefinition": {
    "rules": [
      {
        "field": "encryption.enabled",
        "operator": "equals",
        "value": true
      },
      {
        "field": "accessControl.mfa",
        "operator": "equals",
        "value": true
      }
    ]
  },
  "targetResourceTypes": ["addon", "app", "workflow"],
  "complianceFrameworks": ["hipaa", "hitrust"],
  "tags": ["healthcare", "phi", "encryption"],
  "isPublic": true,
  "isVerified": true,
  "published": true,
  "organizationId": "org_xyz789",
  "reviews": [
    {
      "userId": "user_003",
      "rating": 5,
      "comment": "Comprehensive HIPAA coverage",
      "createdAt": "2025-03-15T12:00:00Z"
    }
  ],
  "averageRating": 4.8,
  "createdAt": "2025-02-01T08:00:00Z",
  "updatedAt": "2025-03-15T12:00:00Z"
}

---

Policies

---

GET /api/v1/governance/policies

List all governance policies accessible to the authenticated user.

Scope: governance:read

Query Parameters

Parameter	Type	Required	Default	Description
search	string	No	—	Search by policy name or description
status	string	No	—	Filter by status: active, draft, archived
category	string	No	—	Filter by category: security, compliance, operational, data
isActive	boolean	No	—	Filter by active state
limit	integer	No	20	Maximum number of results to return (1-100)
offset	integer	No	0	Number of results to skip for pagination
sort	string	No	createdAt:desc	Sort field and direction, e.g. name:asc, severity:desc

Response 200 OK

{
  "data": [
    {
      "id": "pol_abc123",
      "name": "Data Encryption at Rest",
      "description": "Ensures all persistent storage volumes use AES-256 encryption",
      "status": "active",
      "category": "security",
      "severity": "high",
      "rules": [],
      "organizationId": "org_xyz789",
      "isActive": true,
      "createdAt": "2025-03-01T10:00:00Z",
      "updatedAt": "2025-03-15T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 24,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

---

POST /api/v1/governance/policies

Create a new governance policy.

Scope: governance:write

Request Body

Field	Type	Required	Description
name	string	Yes	Human-readable name for the policy
category	string	Yes	Policy category: security, compliance, operational, data
severity	string	Yes	Severity level: critical, high, medium, low
description	string	No	Detailed description of the policy
rules	array	No	Array of rule objects defining policy conditions
isActive	boolean	No	Whether the policy is active (default: true)

{
  "name": "Minimum TLS Version",
  "category": "security",
  "severity": "critical",
  "description": "Enforces TLS 1.2 or higher for all service endpoints",
  "rules": [
    {
      "field": "tls.minVersion",
      "operator": "gte",
      "value": "1.2"
    }
  ],
  "isActive": true
}

Response 201 Created

Returns the full Policy object.

---

GET /api/v1/governance/policies/:id

Retrieve a single governance policy by its ID.

Scope: governance:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The policy ID

Response 200 OK

Returns the full Policy object.

---

PUT /api/v1/governance/policies/:id

Update an existing governance policy. Only provided fields are updated.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The policy ID

Request Body

Field	Type	Required	Description
name	string	No	Updated policy name
description	string	No	Updated description
category	string	No	Updated category
severity	string	No	Updated severity level
rules	array	No	Updated rule definitions
isActive	boolean	No	Updated active state

{
  "severity": "critical",
  "rules": [
    {
      "field": "tls.minVersion",
      "operator": "gte",
      "value": "1.3"
    }
  ]
}

Response 200 OK

Returns the updated Policy object.

---

DELETE /api/v1/governance/policies/:id

Permanently delete a governance policy. Active policy instances must be resolved before deletion.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The policy ID

Response 204 No Content

No response body.

---

POST /api/v1/governance/policies/import-yaml

Import a governance policy from a YAML definition. Useful for infrastructure-as-code workflows.

Scope: governance:write

Request Body

Field	Type	Required	Description
yaml	string	Yes	YAML string containing the policy definition

{
  "yaml": "name: Network Segmentation\ncategory: security\nseverity: high\nrules:\n  - field: network.isolated\n    operator: equals\n    value: true"
}

Response 201 Created

Returns the created Policy object.

---

GET /api/v1/governance/instances

List policy instances. A policy instance represents the application of a policy to a specific resource.

Scope: governance:read

Query Parameters

Parameter	Type	Required	Default	Description
policyId	string	No	—	Filter by policy ID
status	string	No	—	Filter by status: pending, submitted, approved, denied
resourceType	string	No	—	Filter by resource type: addon, app, workflow, model
resourceId	string	No	—	Filter by specific resource ID
limit	integer	No	20	Maximum number of results to return (1-100)
offset	integer	No	0	Number of results to skip for pagination
sort	string	No	createdAt:desc	Sort field and direction

Response 200 OK

{
  "data": [
    {
      "id": "pinst_def456",
      "policyId": "pol_abc123",
      "resourceId": "addon_ghi789",
      "resourceType": "addon",
      "status": "approved",
      "result": {
        "compliant": true,
        "checks": 5,
        "passed": 5,
        "failed": 0
      },
      "submittedAt": "2025-03-10T09:00:00Z",
      "reviewedAt": "2025-03-10T11:00:00Z",
      "reviewedBy": "user_002",
      "comments": [],
      "createdAt": "2025-03-10T08:00:00Z",
      "updatedAt": "2025-03-10T11:00:00Z"
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

---

POST /api/v1/governance/instances

Create a new policy instance, binding a policy to a specific resource for evaluation.

Scope: governance:write

Request Body

Field	Type	Required	Description
policyId	string	Yes	The policy ID to apply
resourceId	string	Yes	The target resource ID
resourceType	string	Yes	The target resource type: addon, app, workflow, model

{
  "policyId": "pol_abc123",
  "resourceId": "addon_ghi789",
  "resourceType": "addon"
}

Response 201 Created

Returns the full PolicyInstance object.

---

POST /api/v1/governance/instances/:id/submit

Submit a policy instance for review. The policy is evaluated against the bound resource and the result is recorded.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The policy instance ID

Response 200 OK

{
  "id": "pinst_def456",
  "status": "submitted",
  "result": {
    "compliant": true,
    "checks": 5,
    "passed": 5,
    "failed": 0
  },
  "submittedAt": "2025-03-10T09:00:00Z",
  "updatedAt": "2025-03-10T09:00:00Z"
}

---

POST /api/v1/governance/instances/:id/approve

Approve a submitted policy instance. Only users with governance review permissions can approve.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The policy instance ID

Request Body

Field	Type	Required	Description
comment	string	No	Optional approval comment
conditions	array	No	Optional conditions attached to the approval

{
  "comment": "All encryption requirements satisfied."
}

Response 200 OK

{
  "id": "pinst_def456",
  "status": "approved",
  "reviewedAt": "2025-03-10T11:00:00Z",
  "reviewedBy": "user_002",
  "updatedAt": "2025-03-10T11:00:00Z"
}

---

POST /api/v1/governance/instances/:id/deny

Deny a submitted policy instance with an explanation.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The policy instance ID

Request Body

Field	Type	Required	Description
reason	string	No	Reason for denial
remediation	string	No	Suggested remediation steps

{
  "reason": "TLS version 1.1 detected on endpoint",
  "remediation": "Upgrade TLS configuration to version 1.2 or higher"
}

Response 200 OK

{
  "id": "pinst_def456",
  "status": "denied",
  "reviewedAt": "2025-03-10T11:00:00Z",
  "reviewedBy": "user_002",
  "updatedAt": "2025-03-10T11:00:00Z"
}

---

POST /api/v1/governance/instances/:id/comment

Add a comment to a policy instance for discussion or audit trail purposes.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The policy instance ID

Request Body

Field	Type	Required	Description
comment	string	Yes	The comment text

{
  "comment": "Verified encryption configuration with ops team."
}

Response 200 OK

{
  "id": "pinst_def456",
  "comments": [
    {
      "userId": "user_001",
      "comment": "Verified encryption configuration with ops team.",
      "createdAt": "2025-03-10T10:30:00Z"
    }
  ],
  "updatedAt": "2025-03-10T10:30:00Z"
}

---

GET /api/v1/governance/enforcement/check

Check enforcement status for a specific resource. Returns all applicable policies and their compliance state.

Scope: governance:read

Query Parameters

Parameter	Type	Required	Default	Description
resourceId	string	Yes	—	The resource ID to check
resourceType	string	Yes	—	The resource type: addon, app, workflow, model
environment	string	No	—	Filter by environment: development, staging, production

Response 200 OK

{
  "resourceId": "addon_ghi789",
  "resourceType": "addon",
  "compliant": true,
  "policies": [
    {
      "policyId": "pol_abc123",
      "name": "Data Encryption at Rest",
      "status": "compliant",
      "severity": "high"
    },
    {
      "policyId": "pol_mno345",
      "name": "Network Segmentation",
      "status": "compliant",
      "severity": "medium"
    }
  ],
  "checkedAt": "2025-03-20T14:00:00Z"
}

---

GET /api/v1/governance/metrics

Retrieve aggregated governance metrics across all policies and resources.

Scope: governance:read

Response 200 OK

{
  "totalPolicies": 24,
  "activePolicies": 20,
  "totalInstances": 156,
  "complianceRate": 91.5,
  "byStatus": {
    "approved": 120,
    "denied": 8,
    "submitted": 15,
    "pending": 13
  },
  "bySeverity": {
    "critical": 5,
    "high": 8,
    "medium": 7,
    "low": 4
  },
  "recentActivity": {
    "last24h": 12,
    "last7d": 45,
    "last30d": 156
  },
  "generatedAt": "2025-03-20T14:00:00Z"
}

---

GET /api/v1/governance/resource-types

List all resource types that can be governed by policies.

Scope: governance:read

Response 200 OK

[
  {
    "id": "addon",
    "label": "Add-on",
    "description": "Managed add-on services such as databases, caches, and message brokers"
  },
  {
    "id": "app",
    "label": "Application",
    "description": "Deployed applications and services"
  },
  {
    "id": "workflow",
    "label": "Workflow",
    "description": "Data processing and AI workflows"
  },
  {
    "id": "model",
    "label": "AI Model",
    "description": "Machine learning and AI models"
  }
]

---

Solutions

---

GET /api/v1/governance/solutions

List all governance solutions. A solution groups related resources and policies for unified compliance tracking.

Scope: governance:read

Query Parameters

Parameter	Type	Required	Default	Description
search	string	No	—	Search by solution name or description
team	string	No	—	Filter by owning team
limit	integer	No	20	Maximum number of results to return (1-100)
offset	integer	No	0	Number of results to skip for pagination
sort	string	No	createdAt:desc	Sort field and direction, e.g. name:asc, complianceScore:desc

Response 200 OK

{
  "data": [
    {
      "id": "sol_jkl012",
      "name": "Customer Data Platform",
      "description": "End-to-end solution for customer data management",
      "status": "compliant",
      "organizationId": "org_xyz789",
      "ownership": {
        "team": "data-engineering",
        "owner": "user_001"
      },
      "policies": ["pol_abc123", "pol_mno345"],
      "models": ["model_pqr678"],
      "complianceScore": 94.5,
      "createdAt": "2025-02-15T08:00:00Z",
      "updatedAt": "2025-03-20T16:00:00Z"
    }
  ],
  "pagination": {
    "total": 6,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

---

POST /api/v1/governance/solutions

Create a new governance solution.

Scope: governance:write

Request Body

Field	Type	Required	Description
name	string	Yes	Human-readable name for the solution
description	string	No	Detailed description of the solution
ownership	object	No	Ownership details with team and owner fields
policies	array	No	Array of policy IDs to associate
models	array	No	Array of model IDs included in the solution

{
  "name": "Fraud Detection System",
  "description": "Real-time fraud detection pipeline with ML models",
  "ownership": {
    "team": "security-engineering",
    "owner": "user_005"
  },
  "policies": ["pol_abc123", "pol_mno345"],
  "models": ["model_pqr678"]
}

Response 201 Created

Returns the full Solution object.

---

GET /api/v1/governance/solutions/:id

Retrieve a single solution by its ID.

Scope: governance:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The solution ID

Response 200 OK

Returns the full Solution object.

---

PUT /api/v1/governance/solutions/:id

Update an existing solution. Only provided fields are updated.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The solution ID

Request Body

Field	Type	Required	Description
name	string	No	Updated solution name
description	string	No	Updated description
ownership	object	No	Updated ownership details
policies	array	No	Updated policy ID list
models	array	No	Updated model ID list

{
  "description": "Updated fraud detection pipeline with enhanced ML models",
  "policies": ["pol_abc123", "pol_mno345", "pol_qrs678"]
}

Response 200 OK

Returns the updated Solution object.

---

DELETE /api/v1/governance/solutions/:id

Permanently delete a solution. Associated snapshots and attestations will also be removed.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The solution ID

Response 204 No Content

No response body.

---

POST /api/v1/governance/solutions/:id/export

Export a solution definition including all associated policies, snapshots, and attestations.

Scope: governance:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The solution ID

Response 200 OK

{
  "solution": {
    "id": "sol_jkl012",
    "name": "Customer Data Platform",
    "description": "End-to-end solution for customer data management",
    "ownership": {
      "team": "data-engineering",
      "owner": "user_001"
    }
  },
  "policies": [
    {
      "id": "pol_abc123",
      "name": "Data Encryption at Rest",
      "category": "security",
      "severity": "high",
      "rules": []
    }
  ],
  "snapshots": [],
  "attestations": [],
  "exportedAt": "2025-03-20T14:00:00Z"
}

---

GET /api/v1/governance/snapshots

List compliance snapshots. Snapshots capture the compliance state of a solution at a point in time.

Scope: governance:read

Query Parameters

Parameter	Type	Required	Default	Description
solutionId	string	No	—	Filter by solution ID
snapshotType	string	No	—	Filter by type: manual, scheduled, triggered
frozen	boolean	No	—	Filter by frozen state
limit	integer	No	20	Maximum number of results to return (1-100)
offset	integer	No	0	Number of results to skip for pagination
sort	string	No	createdAt:desc	Sort field and direction

Response 200 OK

{
  "data": [
    {
      "id": "snap_stu901",
      "solutionId": "sol_jkl012",
      "snapshotType": "scheduled",
      "frozen": false,
      "score": 94.5,
      "totalPolicies": 12,
      "compliantPolicies": 11,
      "nonCompliantPolicies": 1,
      "approvedAt": null,
      "approvedBy": null,
      "createdAt": "2025-03-20T00:00:00Z",
      "updatedAt": "2025-03-20T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 30,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

---

POST /api/v1/governance/snapshots

Create a new compliance snapshot for a solution. Evaluates all associated policies and records the current compliance state.

Scope: governance:write

Request Body

Field	Type	Required	Description
solutionId	string	Yes	The solution ID to snapshot

{
  "solutionId": "sol_jkl012"
}

Response 201 Created

Returns the full ComplianceSnapshot object.

---

GET /api/v1/governance/snapshots/:id

Retrieve a single compliance snapshot by its ID.

Scope: governance:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The snapshot ID

Response 200 OK

Returns the full ComplianceSnapshot object.

---

POST /api/v1/governance/snapshots/:id/freeze

Freeze a compliance snapshot, preventing any further modifications. Frozen snapshots serve as immutable compliance records.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The snapshot ID

Response 200 OK

{
  "id": "snap_stu901",
  "frozen": true,
  "updatedAt": "2025-03-20T15:00:00Z"
}

---

POST /api/v1/governance/snapshots/:id/approve

Approve a compliance snapshot, recording the reviewer and timestamp for audit purposes.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The snapshot ID

Response 200 OK

{
  "id": "snap_stu901",
  "approvedAt": "2025-03-20T16:00:00Z",
  "approvedBy": "user_002",
  "updatedAt": "2025-03-20T16:00:00Z"
}

---

GET /api/v1/governance/compliance/dashboard

Retrieve the compliance dashboard with aggregated metrics across all solutions.

Scope: governance:read

Response 200 OK

{
  "overallScore": 92.3,
  "totalSolutions": 6,
  "compliantSolutions": 5,
  "nonCompliantSolutions": 1,
  "totalSnapshots": 30,
  "frozenSnapshots": 12,
  "recentTrend": [
    { "date": "2025-03-14", "score": 89.0 },
    { "date": "2025-03-15", "score": 90.5 },
    { "date": "2025-03-16", "score": 91.0 },
    { "date": "2025-03-17", "score": 91.8 },
    { "date": "2025-03-18", "score": 92.0 },
    { "date": "2025-03-19", "score": 92.1 },
    { "date": "2025-03-20", "score": 92.3 }
  ],
  "generatedAt": "2025-03-20T14:00:00Z"
}

---

GET /api/v1/governance/compliance/history

Retrieve compliance score history for trend analysis.

Scope: governance:read

Query Parameters

Parameter	Type	Required	Default	Description
solutionId	string	No	—	Filter history to a specific solution
days	integer	No	30	Number of days of history to return

Response 200 OK

{
  "solutionId": "sol_jkl012",
  "history": [
    {
      "date": "2025-02-20",
      "score": 85.0,
      "totalPolicies": 10,
      "compliantPolicies": 8
    },
    {
      "date": "2025-03-01",
      "score": 90.0,
      "totalPolicies": 11,
      "compliantPolicies": 10
    },
    {
      "date": "2025-03-20",
      "score": 94.5,
      "totalPolicies": 12,
      "compliantPolicies": 11
    }
  ],
  "period": {
    "start": "2025-02-18",
    "end": "2025-03-20",
    "days": 30
  }
}

---

Attestations

---

GET /api/v1/governance/attestations

List attestations. Attestations are formal certifications that a solution meets specific compliance requirements.

Scope: governance:read

Query Parameters

Parameter	Type	Required	Default	Description
solutionId	string	No	—	Filter by solution ID
snapshotId	string	No	—	Filter by snapshot ID
type	string	No	—	Filter by attestation type: soc2, hipaa, gdpr, iso27001, custom
revoked	boolean	No	—	Filter by revocation status
limit	integer	No	20	Maximum number of results to return (1-100)
offset	integer	No	0	Number of results to skip for pagination
sort	string	No	createdAt:desc	Sort field and direction

Response 200 OK

{
  "data": [
    {
      "id": "att_vwx234",
      "solutionId": "sol_jkl012",
      "snapshotId": "snap_stu901",
      "type": "soc2",
      "status": "active",
      "attestedBy": "user_001",
      "attestedAt": "2025-03-21T10:00:00Z",
      "evidence": {
        "documentUrl": "https://example.com/evidence/soc2-report.pdf",
        "notes": "Annual SOC 2 Type II audit completed"
      },
      "expiration": "2026-03-21T10:00:00Z",
      "revokedAt": null,
      "revokedBy": null,
      "createdAt": "2025-03-21T10:00:00Z",
      "updatedAt": "2025-03-21T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 8,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

---

POST /api/v1/governance/attestations

Create a new attestation for a compliance snapshot.

Scope: governance:write

Request Body

Field	Type	Required	Description
snapshotId	string	Yes	The compliance snapshot ID to attest
type	string	Yes	Attestation type: soc2, hipaa, gdpr, iso27001, custom
evidence	object	No	Supporting evidence with documentUrl and notes fields
expiration	string	No	ISO 8601 expiration date for the attestation

{
  "snapshotId": "snap_stu901",
  "type": "gdpr",
  "evidence": {
    "documentUrl": "https://example.com/evidence/gdpr-assessment.pdf",
    "notes": "GDPR Data Protection Impact Assessment completed"
  },
  "expiration": "2026-03-21T10:00:00Z"
}

Response 201 Created

Returns the full Attestation object.

---

POST /api/v1/governance/attestations/:id/revoke

Revoke an active attestation. Revoked attestations remain in the system for audit purposes but are no longer considered valid.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The attestation ID

Request Body

Field	Type	Required	Description
reason	string	No	Reason for revocation

{
  "reason": "Compliance gap identified during internal audit"
}

Response 200 OK

{
  "id": "att_vwx234",
  "status": "revoked",
  "revokedAt": "2025-04-01T09:00:00Z",
  "revokedBy": "user_002",
  "updatedAt": "2025-04-01T09:00:00Z"
}

---

GET /api/v1/governance/attestations/summary

Retrieve summary statistics for all attestations.

Scope: governance:read

Response 200 OK

{
  "total": 18,
  "active": 14,
  "revoked": 2,
  "expired": 2,
  "byType": {
    "soc2": 5,
    "hipaa": 4,
    "gdpr": 4,
    "iso27001": 3,
    "custom": 2
  },
  "expiringWithin30Days": 3,
  "generatedAt": "2025-03-20T14:00:00Z"
}

---

Templates

---

GET /api/v1/governance/templates

List policy templates. Templates provide pre-built policy definitions for common compliance frameworks.

Scope: governance:read

Query Parameters

Parameter	Type	Required	Default	Description
search	string	No	—	Search by template name or description
category	string	No	—	Filter by category: security, compliance, operational, healthcare, financial
resourceType	string	No	—	Filter by target resource type
verified	boolean	No	—	Filter by verified status
framework	string	No	—	Filter by compliance framework: soc2, hipaa, gdpr, iso27001, pci-dss
limit	integer	No	20	Maximum number of results to return (1-100)
offset	integer	No	0	Number of results to skip for pagination
sort	string	No	createdAt:desc	Sort field and direction, e.g. name:asc, averageRating:desc

Response 200 OK

{
  "data": [
    {
      "id": "tmpl_yza567",
      "name": "HIPAA Data Protection",
      "description": "Pre-built policy template for HIPAA data protection compliance",
      "category": "healthcare",
      "policyDefinition": {
        "rules": []
      },
      "targetResourceTypes": ["addon", "app", "workflow"],
      "complianceFrameworks": ["hipaa", "hitrust"],
      "tags": ["healthcare", "phi", "encryption"],
      "isPublic": true,
      "isVerified": true,
      "published": true,
      "organizationId": "org_xyz789",
      "reviews": [],
      "averageRating": 4.8,
      "createdAt": "2025-02-01T08:00:00Z",
      "updatedAt": "2025-03-15T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

---

POST /api/v1/governance/templates

Create a new policy template.

Scope: governance:write

Request Body

Field	Type	Required	Description
name	string	Yes	Human-readable name for the template
category	string	Yes	Template category: security, compliance, operational, healthcare, financial
policyDefinition	object	Yes	The policy definition with rules array
description	string	No	Detailed description of the template
targetResourceTypes	array	No	Array of resource types this template applies to
complianceFrameworks	array	No	Array of compliance framework identifiers
tags	array	No	Array of searchable tags
isPublic	boolean	No	Whether the template is publicly visible (default: false)

{
  "name": "PCI-DSS Cardholder Data Protection",
  "category": "financial",
  "policyDefinition": {
    "rules": [
      {
        "field": "encryption.atRest",
        "operator": "equals",
        "value": true
      },
      {
        "field": "encryption.inTransit",
        "operator": "equals",
        "value": true
      },
      {
        "field": "accessControl.rbac",
        "operator": "equals",
        "value": true
      }
    ]
  },
  "description": "Ensures PCI-DSS compliance for cardholder data environments",
  "targetResourceTypes": ["addon", "app"],
  "complianceFrameworks": ["pci-dss"],
  "tags": ["payment", "cardholder", "encryption"],
  "isPublic": true
}

Response 201 Created

Returns the full PolicyTemplate object.

---

GET /api/v1/governance/templates/:id

Retrieve a single policy template by its ID.

Scope: governance:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The template ID

Response 200 OK

Returns the full PolicyTemplate object.

---

PUT /api/v1/governance/templates/:id

Update an existing policy template. Only provided fields are updated. Published templates require a new version.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The template ID

Request Body

Field	Type	Required	Description
name	string	No	Updated template name
description	string	No	Updated description
category	string	No	Updated category
policyDefinition	object	No	Updated policy definition
targetResourceTypes	array	No	Updated target resource types
complianceFrameworks	array	No	Updated compliance frameworks
tags	array	No	Updated tags
isPublic	boolean	No	Updated visibility

{
  "description": "Updated PCI-DSS template with v4.0 requirements",
  "policyDefinition": {
    "rules": [
      {
        "field": "encryption.atRest",
        "operator": "equals",
        "value": true
      },
      {
        "field": "encryption.inTransit",
        "operator": "equals",
        "value": true
      },
      {
        "field": "encryption.algorithm",
        "operator": "in",
        "value": ["AES-256", "AES-128"]
      }
    ]
  }
}

Response 200 OK

Returns the updated PolicyTemplate object.

---

DELETE /api/v1/governance/templates/:id

Permanently delete a policy template. Published templates cannot be deleted if policies have been created from them.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The template ID

Response 204 No Content

No response body.

---

POST /api/v1/governance/templates/:id/use

Create a new governance policy from a template. The template's policy definition is copied into a new policy.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The template ID

Request Body

Field	Type	Required	Description
name	string	No	Override the policy name (defaults to template name)
description	string	No	Override the policy description
severity	string	No	Override the severity level

{
  "name": "Production PCI-DSS Policy",
  "severity": "critical"
}

Response 201 Created

Returns the created Policy object.

---

POST /api/v1/governance/templates/:id/publish

Publish a policy template, making it available for use by other organizations (if isPublic is true).

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The template ID

Response 200 OK

{
  "id": "tmpl_yza567",
  "published": true,
  "updatedAt": "2025-03-20T15:00:00Z"
}

---

POST /api/v1/governance/templates/:id/review

Submit a review for a published policy template.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The template ID

Request Body

Field	Type	Required	Description
rating	integer	Yes	Rating from 1 to 5
comment	string	No	Review comment

{
  "rating": 5,
  "comment": "Comprehensive coverage of PCI-DSS v4.0 requirements. Easy to customize."
}

Response 200 OK

{
  "id": "tmpl_yza567",
  "reviews": [
    {
      "userId": "user_003",
      "rating": 5,
      "comment": "Comprehensive coverage of PCI-DSS v4.0 requirements. Easy to customize.",
      "createdAt": "2025-03-20T16:00:00Z"
    }
  ],
  "averageRating": 4.9,
  "updatedAt": "2025-03-20T16:00:00Z"
}

---

Error Responses

All endpoints may return the following error responses:

Status	Description
400 Bad Request	Invalid request body or parameters
401 Unauthorized	Missing or invalid API key
403 Forbidden	Insufficient scope for the requested operation
404 Not Found	Resource not found or not accessible
409 Conflict	Conflicting state transition or duplicate name
422 Unprocessable Entity	Validation error on request body
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Unexpected server error

{
  "error": {
    "code": "policy_in_use",
    "message": "Cannot delete policy: 3 active instances exist",
    "status": 409
  }
}