Platform Hanzo KMS Internals Permissions Project Permissions Comprehensive guide to Hanzo KMS's project-level permissions
Hanzo KMS's project permissions system follows a role-based access control (RBAC) model built on a subject-action-object framework. At the project level, these permissions determine what actions users/machines can perform on various resources within a specific project.
Each permission consists of:
Subject : The resource the permission applies to (e.g., secrets, members, settings)
Action : The operation that can be performed (e.g., read, create, edit, delete)
Some project-level resources—specifically secrets, secret-folders, secret-imports, dynamic-secrets, secret-syncs, secret-rotation, identity, app-connections, mcp-endpoints, and pam-accounts—support conditional permissions and permission inversion for more granular access control. Conditions allow you to specify criteria (like environment, secret path, tags, app connection ID, identity ID, resource name, or endpoint name) that must be met for the permission to apply.
Below is a comprehensive list of all available project-level subjects and their supported actions.
Action Description readView project roles and their assigned permissions createCreate new project roles editModify existing project roles deleteRemove project roles
Action Description readView project members createAdd new members to the project editModify member details deleteRemove members from the project grant-privilegesChange permission levels of project members
Action Description readView project groups createCreate new groups within the project editModify existing groups deleteRemove groups from the project grant-privilegesChange permission levels of project groups
Supports conditions and permission inversion.
Action Description Condition keys readView project identities identityIdcreateAdd new identities to project identityIdeditModify project identities identityIddeleteRemove identities from project identityIdgrant-privilegesChange permission levels of project identities identityId
Action Description readView project settings createAdd new project configuration settings editModify project settings deleteRemove project settings
Action Description readView project environments createAdd new environments to the project editModify existing environments deleteRemove environments from the project
Action Description readView project tags createCreate new tags for organizing resources editModify existing tags deleteRemove tags from the project
Action Description editModify workspace settings deleteDelete the workspace
Action Description readView IP allowlists createAdd new IP addresses or ranges to allowlists editModify existing IP allowlist entries deleteRemove IP addresses from allowlists
Action Description readView audit logs of actions performed within the project
Action Description readView configured integrations createAdd new third-party integrations editModify integration settings deleteRemove integrations
Action Description readView webhook configurations createAdd new webhooks editModify webhook endpoints or triggers deleteRemove webhooks
Action Description readView service tokens createCreate new service tokens for API access editModify token properties deleteRevoke or remove service tokens
Supports conditions and permission inversion.
Action Description Condition keys read-app-connectionsView app connection configurations connectionIdcreate-app-connectionsCreate new app connections connectionIdedit-app-connectionsModify existing app connections connectionIddelete-app-connectionsRemove app connections connectionIdconnect-app-connectionsUse app connections connectionId
Supports conditions and permission inversion.
Action Description Condition keys readView secrets and their values. This action is the equivalent of granting both describeSecret and readValue. The read action is considered legacy . You should use the describeSecret and/or readValue actions instead. environment, secretPath, secretName, secretTagsdescribeSecretView secret details such as key, path, metadata, tags, and more. If you are using the API, you can pass viewSecretValue: false to the API call to retrieve secrets without their values. environment, secretPath, secretName, secretTagsreadValueView the value of a secret. In order to read secret values, the describeSecret action must also be granted. environment, secretPath, secretName, secretTagscreateAdd new secrets to the project environment, secretPath, secretName, secretTagseditModify existing secret values environment, secretPath, secretName, secretTagsdeleteRemove secrets from the project environment, secretPath, secretName, secretTagsimportSecretImport secrets environmentduplicateSecretDuplicate secrets environment, secretPath, secretName
Supports conditions and permission inversion.
Action Description Condition keys readView secret folders environment, secretPathcreateCreate new folders environment, secretPatheditModify folder properties environment, secretPathdeleteRemove secret folders environment, secretPath
Supports conditions and permission inversion.
Action Description Condition keys readView secret imports environment, secretPathcreateCreate secret imports environment, secretPatheditModify secret imports environment, secretPathdeleteRemove secret imports environment, secretPath
Action Description subscribe-to-creation-eventsSubscribe to events when secrets are created subscribe-to-update-eventsSubscribe to events when secrets are updated subscribe-to-deletion-eventsSubscribe to events when secrets are deleted subscribe-to-import-mutation-eventsSubscribe to events when secrets are modified through imports
Action Description readView secret versions and snapshots createRoll back secrets to snapshots
Action Description readView commits and changes across folders perform-rollbackRoll back commits changes and restore folders to previous state
Action Description readView approval policies and requests createCreate new approval policies editModify approval policies deleteRemove approval policies allow-change-bypassAllow request creators to merge changes without approval in break-glass situations allow-access-bypassAllow request creators to access secrets without approval in break-glass situations
Action Description readList and view all secret approval requests in the project
Project admins and users with Secret Approval Requests (secret-approval-request) Read can view all approval requests; others only see requests where they are committer or approver. Secret values in requests follow secrets.readValue for the secret's environment/path, or reviewer access.
Supports conditions and permission inversion.
Action Description Condition keys readView secret rotation configurations environment, secretPath, connectionIdread-generated-credentialsView the generated credentials of a rotation environment, secretPath, connectionIdcreateSet up secret rotation configurations environment, secretPath, connectionIdeditModify secret rotation configurations environment, secretPath, connectionIdrotate-secretsRotate the generated credentials of a rotation environment, secretPath, connectionIddeleteRemove secret rotation configurations environment, secretPath, connectionId
Supports conditions and permission inversion.
Action Description Condition keys readView secret synchronization configurations environment, secretPath, connectionIdcreateCreate new sync configurations environment, secretPath, connectionIdeditModify existing sync settings environment, secretPath, connectionIddeleteRemove sync configurations environment, secretPath, connectionIdsync-secretsExecute synchronization of secrets between systems environment, secretPath, connectionIdimport-secretsImport secrets from sync sources environment, secretPath, connectionIdremove-secretsRemove secrets from sync destinations environment, secretPath, connectionId
Supports conditions and permission inversion.
Action Description Condition keys read-root-credentialView dynamic secret configurations environment, secretPath, metadatacreate-root-credentialCreate dynamic secrets environment, secretPath, metadataedit-root-credentialEdit dynamic secrets environment, secretPath, metadatadelete-root-credentialRemove dynamic secrets environment, secretPath, metadataleaseCreate dynamic secret leases environment, secretPath, metadata
Action Description editModify project KMS settings
Action Description readView Customer-Managed Encryption Keys createAdd new encryption keys editModify key properties deleteRemove encryption keys encryptUse keys for encryption operations decryptUse keys for decryption operations signUse keys for signing operations verifyUse keys for signature verification operations export-private-keyExport key material (private key for asymmetric, secret key for symmetric)
Action Description readView certificate authorities createCreate new certificate authorities editModify CA configurations deleteRemove certificate authorities
Action Description readView certificates read-private-keyRead certificate private key createIssue new certificates deleteRevoke or remove certificates
Action Description readView certificate profiles createCreate new certificate profiles editModify profile configurations deleteRemove certificate profiles issue-certIssue new certificates
Action Description readView certificate policies createCreate new certificate policies editModify policy configurations deleteRemove certificate policies
Action Description readView PKI alert configurations createCreate new alerts for certificate expiry or other PKI events editModify alert settings deleteRemove PKI alerts
Action Description readView PKI resource collections createCreate new collections for organizing PKI resources editModify collection properties deleteRemove PKI collections
Action Description readView PKI discovery configurations createCreate new discovery jobs editModify discovery job configurations deleteRemove discovery jobs run-scanTrigger discovery scans
Action Description readView certificate installations editModify certificate installations deleteRemove certificate installations
Action Description read-data-sourcesView Data Sources create-data-sourcesCreate new Data Sources edit-data-sourcesModify Data Sources delete-data-sourcesRemove Data Sources read-data-source-resourcesView Data Source Resources read-data-source-scansView Data Source Scans trigger-data-source-scansTrigger Data Source Secret Scans
Action Description read-findingsView Secret Scanning Findings update-findingsUpdate Secret Scanning Findings
Action Description read-configsView Secret Scanning Project Configuration update-configsUpdate Secret Scanning Project Configuration
Supports conditions and permission inversion.
Action Description Condition keys readView MCP endpoints namecreateCreate new MCP endpoints nameeditModify MCP endpoint configurations namedeleteRemove MCP endpoints nameconnectConnect AI clients to MCP endpoints name
Supports conditions and permission inversion.
Action Description Condition keys readView PAM accounts the identity is allowed to use resourceName, accountNameaccessRequest or use access to PAM accounts resourceName, accountName
When defining conditions for permissions, you can use the following operators to match values:
Operator Description Type $eqEquals (exact string match) string$neNot equals string$inIn array (matches any value in list) string[]$globGlob pattern matching (supports * and ? wildcards) string$elemMatchElement match for nested objects/arrays object
The following condition keys can be used to restrict permissions. Each key is available only for specific subjects as indicated in the tables above.
Condition key Description Type environmentThe environment slug (e.g., dev, staging, prod) stringsecretPathThe path within an environment (e.g., /app/config) stringsecretNameThe name of a specific secret stringsecretTagsTags associated with secrets string[]metadataKey-value metadata pairs (use with $elemMatch) objectconnectionIdConnection identifier for rotations/syncs stringidentityIdMachine identity identifier stringnameResource name stringresourceNamePAM resource name stringaccountNamePAM account name string
These permission objects are used when creating or updating custom project roles via the API. Each permission in the permissions array defines what actions a role can perform on which resources.
Create a custom role that can only read secrets in the production environment:
curl --request POST \ --url https://app.kms.hanzo.ai/api/v1/projects/{projectId}/roles \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "slug": "production-reader", "name": "Production Reader", "permissions": [ { "subject": "secrets", "action": ["describeSecret", "readValue"], "conditions": { "environment": { "$eq": "production" } } } ] }'
Create a role that can only manage secrets under /app/config/:
curl --request POST \ --url https://app.kms.hanzo.ai/api/v1/projects/{projectId}/roles \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "slug": "config-manager", "name": "Config Manager", "permissions": [ { "subject": "secrets", "action": ["describeSecret", "readValue", "edit"], "conditions": { "secretPath": { "$glob": "/app/config/**" } } } ] }'
Create a role that grants PAM access only to specific database resources:
curl --request POST \ --url https://app.kms.hanzo.ai/api/v1/projects/{projectId}/roles \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "slug": "db-readonly-access", "name": "Database Read-Only Access", "permissions": [ { "subject": "pam-accounts", "action": ["read", "access"], "conditions": { "resourceName": { "$in": ["prod-db-1", "prod-db-2"] }, "accountName": { "$glob": "readonly-*" } } } ] }' How is this guide?
Last updated on