KeyTab API¶

Import, Manage, Discover, and Enforce Cipher Policy on Kerberos KeyTab Files

Document Version: 1.0.41
Last Updated: 2026-04-26

Feature Availability

KeyTab management is available from MazeVault v1.0.36 and must be enabled via the MAZEVAULT_KEYTAB_ENABLED=true environment variable. See Environment Variables.

Endpoints Overview¶

Method	Endpoint	Description
POST	`/api/v1/keytabs`	Import a keytab file
GET	`/api/v1/keytabs`	List all keytabs
GET	`/api/v1/keytabs/:id`	Get keytab by ID
PUT	`/api/v1/keytabs/:id`	Update keytab metadata or binary
DELETE	`/api/v1/keytabs/:id`	Delete keytab
GET	`/api/v1/keytabs/:id/download`	Download keytab binary
GET	`/api/v1/keytabs/:id/history`	List keytab version history
POST	`/api/v1/keytabs/:id/check-compliance`	Check keytab cipher compliance
POST	`/api/v1/keytabs/refresh-compliance`	Refresh compliance for all keytabs
GET	`/api/v1/keytabs/cipher-policy`	Get organization cipher policy
PUT	`/api/v1/keytabs/cipher-policy`	Update organization cipher policy
GET	`/api/v1/keytabs/discovered`	List agent-discovered keytabs
POST	`/api/v1/keytabs/discovered/:id/import`	Import a discovered keytab into management
GET	`/api/v1/keytabs/dashboard`	Get keytab dashboard statistics

Import KeyTab¶

Uploads and registers a new Kerberos keytab file. The binary content must be base64-encoded. MazeVault parses the keytab to extract the principal, realm, KVNO, and encryption types automatically.

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

{
  "name": "app-service-keytab",
  "keytab_data": "<base64-encoded keytab binary>",
  "expires_at": "2027-04-01T00:00:00Z",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "notes": "Service account for the billing application"
}

Request Fields¶

Field	Type	Required	Description
`name`	string	✅	Human-readable name (max 255 chars)
`keytab_data`	string	✅	Base64-encoded keytab file binary
`expires_at`	string (ISO 8601)	—	Expiry timestamp; used for expiry alerts and reports
`project_id`	string (UUID)	—	Associates the keytab with a project
`notes`	string	—	Free-text notes for the keytab (max 1024 chars)

Response `201 Created`¶

{
  "id": "kt_550e8400-e29b-41d4-a716-446655440010",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "app-service-keytab",
  "principal": "app-svc@CORP.EXAMPLE.COM",
  "realm": "CORP.EXAMPLE.COM",
  "kvno": 5,
  "encryption_types": ["aes256-cts-hmac-sha1-96", "aes128-cts-hmac-sha1-96"],
  "status": "active",
  "cipher_compliance": "compliant",
  "source": "import",
  "storage_mode": "full",
  "offload_status": "local",
  "version": 1,
  "entry_count": 2,
  "keytab_hash": "e3b0c44298fc1c149afbf4c8996fb924",
  "expires_at": "2027-04-01T00:00:00Z",
  "notes": "Service account for the billing application",
  "created_at": "2026-04-26T10:00:00Z",
  "updated_at": "2026-04-26T10:00:00Z"
}

Cipher Compliance

After import, MazeVault automatically checks the keytab's encryption types against the organization's configured cipher policy. The cipher_compliance field reflects the result (compliant, warning, or non_compliant).

List KeyTabs¶

GET /api/v1/keytabs?page=1&limit=25 HTTP/1.1
Authorization: Bearer <token>

Query Parameters¶

Parameter	Type	Description
`project_id`	string (UUID)	Filter by project
`status`	string	Filter by status (`active`, `disabled`, `expired`)
`cipher_compliance`	string	Filter by compliance status (`compliant`, `warning`, `non_compliant`)
`realm`	string	Filter by Kerberos realm
`principal`	string	Filter by principal name (partial match)
`source`	string	Filter by source (`import`, `discovered`, `agent`)
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 25, max: 100)

Response `200 OK`¶

{
  "data": [
    {
      "id": "kt_550e8400-e29b-41d4-a716-446655440010",
      "name": "app-service-keytab",
      "principal": "app-svc@CORP.EXAMPLE.COM",
      "realm": "CORP.EXAMPLE.COM",
      "kvno": 5,
      "encryption_types": ["aes256-cts-hmac-sha1-96"],
      "status": "active",
      "cipher_compliance": "compliant",
      "source": "import",
      "version": 1,
      "entry_count": 2,
      "expires_at": "2027-04-01T00:00:00Z",
      "created_at": "2026-04-26T10:00:00Z",
      "updated_at": "2026-04-26T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 25
}

Get KeyTab¶

GET /api/v1/keytabs/kt_550e8400-e29b-41d4-a716-446655440010 HTTP/1.1
Authorization: Bearer <token>

Response `200 OK`¶

Returns the full KeyTabResponse object. The binary keytab data is not included in this response. Use the Download KeyTab endpoint to retrieve the binary.

See the Import KeyTab response fields for the complete field list.

Update KeyTab¶

Updates keytab metadata or replaces the keytab binary. To replace the binary, include a new keytab_data value. A new version record is created automatically when the binary changes.

PUT /api/v1/keytabs/kt_550e8400-e29b-41d4-a716-446655440010 HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "app-service-keytab-v2",
  "keytab_data": "<base64-encoded new keytab binary>",
  "expires_at": "2028-04-01T00:00:00Z",
  "notes": "Updated after annual Kerberos key rotation",
  "status": "active"
}

Request Fields¶

Field	Type	Required	Description
`name`	string	—	New display name
`keytab_data`	string	—	Base64-encoded replacement keytab binary
`expires_at`	string (ISO 8601)	—	New expiry timestamp
`notes`	string	—	Updated notes
`status`	string	—	New status (`active`, `disabled`)

Response `200 OK`¶

Returns the updated KeyTabResponse object with incremented version.

Delete KeyTab¶

Soft-deletes a keytab. The keytab is not permanently removed and can be audited in the audit log.

DELETE /api/v1/keytabs/kt_550e8400-e29b-41d4-a716-446655440010 HTTP/1.1
Authorization: Bearer <token>

Response `204 No Content`¶

Download KeyTab¶

Retrieves the raw keytab binary. The response is the binary file with Content-Type: application/octet-stream.

GET /api/v1/keytabs/kt_550e8400-e29b-41d4-a716-446655440010/download HTTP/1.1
Authorization: Bearer <token>

Response `200 OK`¶

Content-Type: application/octet-stream
Content-Disposition: attachment; filename="app-service-keytab.keytab"

<binary keytab data>

Access Control

Downloading keytab binary data requires elevated permissions. All downloads are recorded in the audit log.

Get KeyTab Version History¶

Returns the full list of version records for a keytab, ordered newest-first.

GET /api/v1/keytabs/kt_550e8400-e29b-41d4-a716-446655440010/history HTTP/1.1
Authorization: Bearer <token>

Response `200 OK`¶

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440020",
    "keytab_id": "kt_550e8400-e29b-41d4-a716-446655440010",
    "version": 2,
    "encryption_types": ["aes256-cts-hmac-sha1-96"],
    "kvno": 6,
    "keytab_hash": "a665a45920422f9d417e4867efdc4fb8",
    "changed_by": "550e8400-e29b-41d4-a716-446655440099",
    "change_reason": "Annual Kerberos key rotation",
    "created_at": "2027-04-01T08:00:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440021",
    "keytab_id": "kt_550e8400-e29b-41d4-a716-446655440010",
    "version": 1,
    "encryption_types": ["aes256-cts-hmac-sha1-96", "aes128-cts-hmac-sha1-96"],
    "kvno": 5,
    "keytab_hash": "e3b0c44298fc1c149afbf4c8996fb924",
    "changed_by": "550e8400-e29b-41d4-a716-446655440099",
    "change_reason": "Initial import",
    "created_at": "2026-04-26T10:00:00Z"
  }
]

Check Cipher Compliance¶

Evaluates the cipher compliance of a single keytab against the organization's current cipher policy and updates the stored cipher_compliance status.

POST /api/v1/keytabs/kt_550e8400-e29b-41d4-a716-446655440010/check-compliance HTTP/1.1
Authorization: Bearer <token>

Response `200 OK`¶

{
  "cipher_compliance": "warning",
  "cipher_violations": {
    "aes128-cts-hmac-sha1-96": "deprecated cipher — scheduled for removal"
  }
}

Compliance Status Values¶

Value	Meaning
`compliant`	All encryption types are in the organization's allowed list
`warning`	One or more types are in the deprecated list but not yet blocked
`non_compliant`	One or more types are not in the allowed list (blocked if `enforcement_mode` is `enforce`)

Refresh All Compliance¶

Re-evaluates cipher compliance for all keytabs in the organization against the current cipher policy. Useful after updating the policy.

POST /api/v1/keytabs/refresh-compliance HTTP/1.1
Authorization: Bearer <token>

Response `200 OK`¶

{
  "updated": 14
}

Get Cipher Policy¶

Returns the organization's current cipher policy for keytab enforcement.

GET /api/v1/keytabs/cipher-policy HTTP/1.1
Authorization: Bearer <token>

Response `200 OK`¶

{
  "id": "550e8400-e29b-41d4-a716-446655440050",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "allowed_ciphers": [
    "aes256-cts-hmac-sha1-96",
    "aes256-cts-hmac-sha384-192"
  ],
  "deprecated_ciphers": [
    "aes128-cts-hmac-sha1-96"
  ],
  "enforcement_mode": "warn",
  "created_at": "2026-04-26T10:00:00Z",
  "updated_at": "2026-04-26T10:00:00Z"
}

Update Cipher Policy¶

Sets the allowed and deprecated cipher lists and the enforcement mode for the organization.

PUT /api/v1/keytabs/cipher-policy HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "allowed_ciphers": [
    "aes256-cts-hmac-sha1-96",
    "aes256-cts-hmac-sha384-192"
  ],
  "deprecated_ciphers": [
    "aes128-cts-hmac-sha1-96"
  ],
  "enforcement_mode": "warn"
}

Request Fields¶

Field	Type	Required	Description
`allowed_ciphers`	array of strings	✅	Cipher suites permitted in managed keytabs
`deprecated_ciphers`	array of strings	✅	Cipher suites that trigger a `warning` (must be subset of `allowed_ciphers`)
`enforcement_mode`	string	✅	`warn` — flag violations only; `enforce` — reject keytabs with disallowed ciphers

Response `200 OK`¶

Returns the updated CipherPolicyResponse object.

After Updating Policy

Run Refresh All Compliance after updating the cipher policy to immediately re-evaluate all stored keytabs.

List Discovered KeyTabs¶

Lists keytab files discovered on agent hosts via automatic filesystem scanning. Discovered keytabs can be reviewed and selectively imported into full management.

GET /api/v1/keytabs/discovered?page=1&limit=25 HTTP/1.1
Authorization: Bearer <token>

Query Parameters¶

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 25, max: 100)

Response `200 OK`¶

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440060",
      "organization_id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_id": "550e8400-e29b-41d4-a716-446655440070",
      "file_path": "/etc/security/keytabs/app-svc.keytab",
      "principal": "app-svc@CORP.EXAMPLE.COM",
      "realm": "CORP.EXAMPLE.COM",
      "encryption_types": ["aes256-cts-hmac-sha1-96"],
      "kvno": 5,
      "file_permissions": "0600",
      "file_owner": "app-svc",
      "keytab_hash": "e3b0c44298fc1c149afbf4c8996fb924",
      "is_managed": false,
      "managed_keytab_id": null,
      "state": "discovered",
      "discovered_at": "2026-04-25T06:00:00Z",
      "last_seen_at": "2026-04-26T06:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 25
}

Discovered KeyTab State Values¶

State	Meaning
`discovered`	Found by agent, not yet reviewed
`imported`	Imported into MazeVault management
`ignored`	Marked as not requiring management
`stale`	No longer present on the agent host

Import Discovered KeyTab¶

Imports a discovered keytab into full MazeVault management. The agent uploads the keytab binary and it is stored, parsed, and compliance-checked.

POST /api/v1/keytabs/discovered/550e8400-e29b-41d4-a716-446655440060/import HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "app-svc-discovered",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "expires_at": "2027-04-01T00:00:00Z"
}

Request Fields¶

Field	Type	Required	Description
`name`	string	—	Display name (defaults to the keytab principal if not provided)
`project_id`	string (UUID)	—	Associates the keytab with a project
`expires_at`	string (ISO 8601)	—	Expiry timestamp

Response `201 Created`¶

Returns the full KeyTabResponse object for the newly managed keytab. The source field is set to discovered.

KeyTab Dashboard¶

Returns aggregated statistics about all keytabs in the organization for dashboard display.

GET /api/v1/keytabs/dashboard HTTP/1.1
Authorization: Bearer <token>

Response `200 OK`¶

{
  "overview": {
    "total": 42,
    "active": 38,
    "expiring_soon": 4,
    "expired": 1,
    "disabled": 0,
    "non_compliant": 2,
    "warning": 5
  },
  "cipher_distribution": [
    {
      "cipher": "aes256-cts-hmac-sha1-96",
      "count": 38
    },
    {
      "cipher": "aes128-cts-hmac-sha1-96",
      "count": 6
    }
  ],
  "expiring_keytabs": [
    {
      "id": "kt_550e8400-e29b-41d4-a716-446655440010",
      "name": "app-service-keytab",
      "principal": "app-svc@CORP.EXAMPLE.COM",
      "expires_at": "2026-05-10T00:00:00Z",
      "days_remaining": 14
    }
  ]
}

Error Responses¶

All endpoints use standard MazeVault error responses:

HTTP Status	Meaning
`400 Bad Request`	Invalid request body, missing required fields, or unparseable keytab binary
`401 Unauthorized`	Missing or invalid bearer token
`403 Forbidden`	Insufficient role permissions for the requested operation
`404 Not Found`	KeyTab or discovered keytab ID does not exist
`409 Conflict`	A keytab with the same hash already exists in the organization (duplicate import)
`503 Service Unavailable`	KeyTab management is disabled (`MAZEVAULT_KEYTAB_ENABLED=false`)

KeyTab API¶

Endpoints Overview¶

Import KeyTab¶

Request Fields¶

Response 201 Created¶

List KeyTabs¶

Query Parameters¶

Response 200 OK¶

Get KeyTab¶

Response 200 OK¶

Update KeyTab¶

Request Fields¶

Response 200 OK¶

Delete KeyTab¶

Response 204 No Content¶

Download KeyTab¶

Response 200 OK¶

Get KeyTab Version History¶

Response 200 OK¶

Check Cipher Compliance¶

Response 200 OK¶

Compliance Status Values¶

Refresh All Compliance¶

Response 200 OK¶

Get Cipher Policy¶

Response 200 OK¶

Update Cipher Policy¶

Request Fields¶

Response 200 OK¶

List Discovered KeyTabs¶

Query Parameters¶

Response 200 OK¶

Discovered KeyTab State Values¶

Import Discovered KeyTab¶

Request Fields¶

Response 201 Created¶

KeyTab Dashboard¶

Response 200 OK¶

Error Responses¶

Related¶

Response `201 Created`¶

Response `200 OK`¶

Response `200 OK`¶

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

Response `200 OK`¶

Response `201 Created`¶

Response `200 OK`¶