Configuration Management API¶

Managed Configuration Files, Agent Discovery Results, Configuration Templates, and Secret Naming Policy

Document Version: 1.0.0
Last Updated: 2026-10-22

Feature Availability

Configuration Management is an Enterprise Function gated by the config_management license feature (PoC and Enterprise licenses). The configuration file, discovery result, and secret naming policy endpoints return 403 Forbidden without it. See Licensing and the Configuration Management Guide.

Endpoints Overview¶

Configuration Files¶

Method	Endpoint	Permission	Description
GET	`/api/v1/config-files`	`config:read`	List managed configuration files
GET	`/api/v1/config-files/:id`	`config:read`	Get a configuration file with versions and secret references
GET	`/api/v1/config-files/overview`	`config:read`	Overview statistics

Discovery Results¶

Method	Endpoint	Permission	Description
GET	`/api/v1/discovery-results`	`config:read`	List agent-reported discovery results
POST	`/api/v1/discovery-results/:id/adopt`	`config:write`	Adopt a result into a managed configuration file
POST	`/api/v1/discovery-results/:id/ignore`	`config:write`	Ignore a result with a reason

Configuration Templates¶

Method	Endpoint	Permission	Description
GET	`/api/v1/organizations/:id/config-templates`	`config:read`	List templates of an organization
POST	`/api/v1/organizations/:id/config-templates`	`config:write`	Create a template
PUT	`/api/v1/organizations/:id/config-templates/:templateId`	`config:write`	Update a template
DELETE	`/api/v1/organizations/:id/config-templates/:templateId`	`config:write`	Delete a template
POST	`/api/v1/organizations/:id/config-templates/validate`	`config:write`	Validate a template definition without saving
POST	`/api/v1/organizations/:id/config-templates/preview`	`config:write`	Preview the effect of a resource visibility policy

Secret Naming Policy¶

Method	Endpoint	Permission	Description
POST	`/api/v1/organizations/:id/secret-naming-policy/check`	`config:read`	Check a secret key against the active policy
GET	`/api/v1/organizations/:id/secret-naming-policy/compliance`	`config:read`	Compliance report across existing secrets
GET	`/api/v1/organizations/:id/secret-naming-policy/suggest`	`config:read`	Suggest naming rules from existing keys
POST	`/api/v1/secret-naming-policy/validate`	`config:write`	Validate a policy definition

Naming convention templates additionally expose render, parse, provision, Terraform export, and cross-validation endpoints under /api/v1/naming-conventions (config:read / config:write); they are not part of the license-gated group.

List Configuration Files¶

GET /api/v1/config-files?project_id=550e8400-e29b-41d4-a716-446655440001 HTTP/1.1
Authorization: ******

Query Parameters¶

Parameter	Type	Description
`agent_id`	UUID	Filter by reporting agent
`project_id`	UUID	Filter by owning project

Response `200 OK`¶

[
  {
    "id": "c1d2e3f4-0000-0000-0000-000000000010",
    "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "project_id": "550e8400-e29b-41d4-a716-446655440001",
    "file_path": "/opt/billing/config/app.yaml",
    "file_name": "app.yaml",
    "file_type": "yaml",
    "file_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "file_size_bytes": 2048,
    "status": "managed",
    "rotation_status": "compliant",
    "integration_status": "pending",
    "compliance_score": 0.92,
    "discovery_method": "filesystem",
    "confidence_score": 0.85,
    "classification": "application",
    "policy_version": "2026-10-01T12:00:00Z-7",
    "discovered_at": "2026-10-20T06:00:00Z",
    "adopted_at": "2026-10-21T09:15:00Z",
    "current_version": 1,
    "secret_count": 3,
    "tags": ["billing", "prod"]
  }
]

Configuration File Fields¶

Field	Description
`status`	`discovered` (pending processing) or `managed` (adopted)
`rotation_status`	`unknown`, `compliant`, or `overdue` — derived from the rotation state of referenced secrets
`classification`	`system`, `application`, or `unknown`
`confidence_score`	Discovery confidence 0–1
`policy_version`	Version of the discovery policy bundle that produced the result
`rewrite_plan`	Proposed secret extraction steps (see guide)
`secret_count` / `secret_refs`	Secrets referenced by the file and their locations
`versions`	Version history (detail endpoint only)

Get Configuration File¶

GET /api/v1/config-files/c1d2e3f4-0000-0000-0000-000000000010 HTTP/1.1
Authorization: ******

Response `200 OK`¶

Returns the configuration file object including versions[] (version number, content hash, change type, change summary, change reason, changed by, approval status, diff stats) and secret_refs[] (secret ID, location path, location line). File content is never returned; only hashes and metadata are exposed.

Configuration Overview¶

GET /api/v1/config-files/overview HTTP/1.1
Authorization: ******

Response `200 OK`¶

{
  "total_files": 42,
  "compliant_files": 35,
  "pending_files": 4,
  "critical_files": 3
}

Field	Meaning
`total_files`	All managed configuration files
`compliant_files`	Files with `rotation_status = compliant`
`pending_files`	Files with `status = discovered`
`critical_files`	Files with `rotation_status = overdue`

List Discovery Results¶

GET /api/v1/discovery-results?status=pending&agent_id=3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1
Authorization: ******

Query Parameters¶

Parameter	Type	Description
`agent_id`	UUID	Filter by reporting agent
`status`	string	`pending` (default view), `adopted`, or `ignored`

Response `200 OK`¶

[
  {
    "id": "d4e5f6a7-0000-0000-0000-000000000020",
    "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "file_path": "/opt/billing/config/app.yaml",
    "file_name": "app.yaml",
    "file_type": "yaml",
    "file_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "file_size_bytes": 2048,
    "discovery_source": "filesystem",
    "confidence_score": 0.85,
    "policy_version": "2026-10-01T12:00:00Z-7",
    "classification": "application",
    "detected_patterns": [
      { "key": "database.password", "line": 14, "severity": "high", "pattern": "generic-password" }
    ],
    "rewrite_plan": [
      {
        "key": "database.password",
        "action": "replace_plaintext",
        "secret_path": "application/app.yaml/database.password",
        "placeholder": "${MAZEVAULT:application/app.yaml/database.password}",
        "change_reason": "Move database password to vault",
        "location_path": "database.password",
        "location_line": 14
      }
    ],
    "potential_secrets": 1,
    "status": "pending"
  }
]

Discovery Result State Values¶

State	Description
`pending`	Waiting for review
`adopted`	Converted into a managed file; `config_file_id` is set
`ignored`	Dismissed; `suppressed_reason` holds the reason

Adopt Discovery Result¶

Creates a managed configuration file from a discovery result, optionally extracting detected secrets into the target project and creating the initial version.

POST /api/v1/discovery-results/d4e5f6a7-0000-0000-0000-000000000020/adopt HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "content": "database:\n  host: db.internal\n  password: s3cr3t\n",
  "extract_secrets": true,
  "initial_comment": "Adopted from billing-01 discovery"
}

Request Fields¶

Field	Type	Required	Description
`project_id`	string (UUID)	✅	Project that will own the configuration file
`content`	string	—	Plain-text file content. When provided, version 1 is created and secret extraction can run
`extract_secrets`	boolean	—	Store detected secret values as project secrets and record `secret_refs`
`initial_comment`	string	—	Change summary stored on version 1

Response `200 OK`¶

Returns the created configuration file object (status: managed, current_version: 1). The operation is audited as ADOPT_CONFIG_DISCOVERY_RESULT.

Ignore Discovery Result¶

POST /api/v1/discovery-results/d4e5f6a7-0000-0000-0000-000000000020/ignore HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "reason": "Sample configuration shipped with the package; no live credentials"
}

Response `200 OK`¶

{ "status": "ignored" }

The operation is audited as IGNORE_CONFIG_DISCOVERY_RESULT.

List Configuration Templates¶

GET /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/config-templates HTTP/1.1
Authorization: ******

Response `200 OK`¶

[
  {
    "id": "e5f6a7b8-0000-0000-0000-000000000030",
    "organization_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Default discovery policy",
    "description": "Scan application directories for configuration files",
    "template_type": "discovery_policy",
    "definition": {
      "scan_paths": ["/opt", "/etc/app"],
      "scan_depth": 4,
      "file_types": ["env", "yaml", "json", "properties"],
      "confidence_threshold": 0.6,
      "auto_adopt": false,
      "classification": {
        "system_paths": ["/etc"],
        "application_paths": ["/opt"]
      },
      "rewrite_plan_rules": [
        {
          "name": "passwords",
          "key_pattern": "(?i)password|passwd|secret",
          "secret_path_template": "{{classification}}/{{file_name}}/{{key}}",
          "placeholder_template": "${MAZEVAULT:{{secret_path}}}",
          "change_reason": "Move credential to vault"
        }
      ]
    },
    "is_active": true,
    "is_default": true,
    "priority": 100
  }
]

Resource visibility policy templates are returned only to callers with administrator rights.

Create Configuration Template¶

POST /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/config-templates HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "name": "Generic secret patterns",
  "description": "Passwords, API keys and tokens",
  "template_type": "secret_pattern",
  "definition": {
    "patterns": [
      { "name": "generic-password", "type": "regex", "regex": "(?i)(password|passwd)\\s*[:=]\\s*\\S+", "severity": "high" },
      { "name": "bearer-token", "type": "regex", "regex": "(?i)bearer\\s+[a-z0-9._-]{20,}", "severity": "critical" }
    ],
    "entropy_threshold": 3.5,
    "min_length": 8,
    "max_length": 512
  },
  "is_active": true,
  "priority": 50
}

Request Fields¶

Field	Type	Required	Description
`name`	string	✅	Template name
`description`	string	—	Description
`template_type`	string	✅	`discovery_policy`, `parser`, `secret_pattern`, `exclusion_rule`, `naming_convention`, `secret_naming_policy`, `resource_visibility_policy`
`definition`	object	✅	Type-specific JSON definition (validated on write)
`is_active`	boolean	—	Only active templates are compiled into the agent policy bundle (default `true`)
`is_default`	boolean	—	Marks the organization default for its type
`priority`	integer	—	Lower values are applied first (default `100`)

Response `201 Created`¶

Returns the created template. If the definition is invalid the API answers 400 Bad Request with details containing the validation result (see below).

Update Configuration Template¶

PUT /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/config-templates/e5f6a7b8-0000-0000-0000-000000000030 HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "is_active": false,
  "priority": 200
}

Partial updates are supported; a changed definition or template_type is re-validated.

Response `200 OK`¶

Returns the updated template.

Delete Configuration Template¶

DELETE /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/config-templates/e5f6a7b8-0000-0000-0000-000000000030 HTTP/1.1
Authorization: ******

Response `204 No Content`¶

Validate Template Definition¶

Validates a definition without persisting it. Use it from CI or before saving a template in the UI.

POST /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/config-templates/validate HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "template_type": "exclusion_rule",
  "definition": {
    "excluded_paths": ["/proc", "/sys"],
    "excluded_extensions": [".log", ".bak"],
    "rules": [
      { "name": "node-modules", "type": "path", "pattern": "node_modules", "is_regex": false, "reason": "Third-party code" }
    ]
  }
}

Response `200 OK`¶

{
  "valid": true,
  "warnings": [
    { "field": "rules[0].pattern", "message": "Pattern is a plain substring; consider anchoring it to a path segment" }
  ]
}

Field	Description
`valid`	`false` when at least one error exists
`errors[]` / `warnings[]`	Issues with `field` and `message`

Preview Template Definition¶

Available for resource_visibility_policy templates. Evaluates the definition against the resources of a project and reports which items would match.

POST /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/config-templates/preview HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "template_type": "resource_visibility_policy",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "environment": "prod",
  "resource_type": "secret",
  "definition": {
    "resource_rules": [
      { "id": "pci-secrets", "resource_type": "secret", "action": "admin_only", "match_mode": "tag", "field": "tags", "exact_values": ["pci"], "description": "Restrict PCI secrets to administrators" }
    ]
  }
}

Response `200 OK`¶

{
  "total_count": 120,
  "matched_count": 18,
  "matched_items": [
    { "resource_type": "secret", "name": "PCI_DB_PASSWORD", "visible_to_non_admin": false, "matched_rule_ids": ["pci-secrets"], "match_reasons": ["tag pci"] }
  ],
  "unmatched_sample": [
    { "resource_type": "secret", "name": "APP_LOG_LEVEL", "visible_to_non_admin": true }
  ],
  "rule_breakdown": [
    { "rule_id": "pci-secrets", "resource_type": "secret", "field": "tags", "match_mode": "tag", "action": "admin_only", "match_count": 18 }
  ],
  "available_facets": [
    { "field": "tags", "values": ["pci", "billing", "internal"] }
  ]
}

Check Secret Name¶

POST /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/secret-naming-policy/check HTTP/1.1
Authorization: ******
Content-Type: application/json

{ "key": "PROD_DATABASE_URL", "environment": "prod" }

Response `200 OK`¶

{
  "allowed": true,
  "results": [
    { "rule_name": "SCREAMING_SNAKE_CASE", "pattern": "^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$", "enforcement": "block", "passed": true, "message": "" }
  ]
}

allowed is false when a rule with enforcement: block fails; rules with enforcement: warn only add entries to warnings.

Secret Naming Compliance¶

GET /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/secret-naming-policy/compliance HTTP/1.1
Authorization: ******

Response `200 OK`¶

{
  "total_secrets": 142,
  "compliant_count": 130,
  "violation_count": 12,
  "compliance_rate": 91.55,
  "rule_stats": [
    { "rule_name": "SCREAMING_SNAKE_CASE", "enforcement": "block", "pass_count": 130, "fail_count": 12 }
  ],
  "violations": [
    { "secret_id": "…", "secret_key": "dbPassword", "project_id": "…", "project_name": "Payment Gateway", "environment": "prod", "rule_name": "SCREAMING_SNAKE_CASE", "enforcement": "block" }
  ]
}

Suggest Naming Rules¶

Analyses existing secret keys and proposes rules that match most of them.

GET /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/secret-naming-policy/suggest HTTP/1.1
Authorization: ******

Response `200 OK`¶

{
  "suggestions": [
    { "name": "SCREAMING_SNAKE_CASE", "pattern": "^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$", "description": "Enforce SCREAMING_SNAKE_CASE convention", "confidence": 0.87, "match_count": 87, "total_keys": 100 }
  ]
}

Validate Secret Naming Policy Definition¶

Validates a secret_naming_policy definition without organization context.

POST /api/v1/secret-naming-policy/validate HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "definition": {
    "rules": [
      { "name": "SCREAMING_SNAKE_CASE", "pattern": "^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$", "enforcement": "block" }
    ]
  }
}

Response `200 OK`¶

{ "valid": true }

Error Responses¶

All endpoints use standard MazeVault error responses:

HTTP Status	Meaning
`400 Bad Request`	Invalid UUID, invalid body, or template definition failed validation (`details` holds the validation result)
`401 Unauthorized`	Missing or invalid bearer token
`403 Forbidden`	Insufficient permission, administrator rights required for resource visibility policies, or the `config_management` license feature is not available
`404 Not Found`	Configuration file, discovery result, or template does not exist
`500 Internal Server Error`	Unexpected failure while adopting a result or extracting secrets

Configuration Management API¶

Endpoints Overview¶

Configuration Files¶

Discovery Results¶

Configuration Templates¶

Secret Naming Policy¶

List Configuration Files¶

Query Parameters¶

Response 200 OK¶

Configuration File Fields¶

Get Configuration File¶

Response 200 OK¶

Configuration Overview¶

Response 200 OK¶

List Discovery Results¶

Query Parameters¶

Response 200 OK¶

Discovery Result State Values¶

Adopt Discovery Result¶

Request Fields¶

Response 200 OK¶

Ignore Discovery Result¶

Response 200 OK¶

List Configuration Templates¶

Response 200 OK¶

Create Configuration Template¶

Request Fields¶

Response 201 Created¶

Update Configuration Template¶

Response 200 OK¶

Delete Configuration Template¶

Response 204 No Content¶

Validate Template Definition¶

Response 200 OK¶

Preview Template Definition¶

Response 200 OK¶

Check Secret Name¶

Response 200 OK¶

Secret Naming Compliance¶

Response 200 OK¶

Suggest Naming Rules¶

Response 200 OK¶

Validate Secret Naming Policy Definition¶

Response 200 OK¶

Error Responses¶

Related¶

Response `200 OK`¶

Response `200 OK`¶

Response `200 OK`¶

Response `200 OK`¶

Response `200 OK`¶

Response `200 OK`¶

Response `200 OK`¶

Response `201 Created`¶

Response `200 OK`¶

Response `204 No Content`¶

Response `200 OK`¶

Response `200 OK`¶

Response `200 OK`¶

Response `200 OK`¶

Response `200 OK`¶

Response `200 OK`¶