Skip to main content

IAM configuration file

Learn about the IAM configuration file structure

Identity and access management users, roles, and policies are defined using a TOML file loaded using the Set IAM configuration REST API endpoint or CLI command.

The TOML file must contain three sections, in any order.


Users are defined with the [users] keyword like this:

role = "<role_name>"

Where <role_name> is any valid string.


Users are defined with the [roles] keyword like this:

policies = [<policies-list>]
capabilities = [<capabilities-list>]


  • <role_name> is any valid string.
  • <policies-list> is a comma-separated list of policies or "*" to indicate that all policies are included.
  • <capabilities-list> is a comma-separated list of capabilities or "*" to indicate that all capabilities are included. These are the capabilities by scope:
POST"CapDataWriter" or "CapDataCreator"
PATCH"CapDataWriter" or "CapDataUpdater"
DELETE"CapDataWriter" or "CapDataDeleter"
Data query/api/pvlt/1.0/data/collections/*/query/objectsPOST"CapDataSearcher"
POST, PATCH, and DELETE"CapTokensWriter"
Tokens query/api/pvlt/1.0/data/collections/*/query/tokensPOST"CapTokensReader"
Tokens rotate/api/pvlt/1.0/data/collections/*/rotate/tokensPOST"CapTokensWriter"
Transaction ID/api/pvlt/1.0/data/collections/*/transaction_idGET"CapTransactionIdReader"
PATCH"CapCryptoDecrypter" and "CapCryptoEncrypter"
Action invoker/api/pvlt/1.0/data/actionsPOST"CapActionsInvoker"
Identity and access management/api/pvlt/1.0/ctl/iamGET"CapIAMReader"
POST, PATCH, and DELETE"CapCodeWriter"
Data types/api/pvlt/1.0/ctl/typesGET"CapTypesReader"
POST, PATCH, and DELETE"CapTypesWriter"
POST, PUSH, PATCH, and DELETE"CapCollectionsWriter"
Garbage collection (pruning)/api/pvlt/1.0/system/admin/lifecycle/gcPOST"CapSystemGCRunner"
Configuration variables/api/pvlt/1.0/system/confvarGET"CapConfvarReader"
POST, PATCH, and DELETE"CapConfvarWriter"
KMS rotate/api/pvlt/1.0/system/admin/keys/rotatePOST"CapKMSWriter"
Export key/api/pvlt/1.0/system/admin/export_keyGET"CapExportKeyReader"
Version/api/pvlt/1.0/system/info/versionAllNot required
System information/api/pvlt/1.0/system/infoGET"CapInfoReader"
Cluster information/api/pvlt/1.0/ctl/info/clusterGET"CapClusterInfoReader"
Health/api/pvlt/1.0/data/info/healthAllNot required
/api/pvlt/1.0/ctl/info/healthAllNot required

The roles ConsoleAdmin and ConsoleReadOnly are used by the Piiano SaaS.


Policies are defined with the [policies] keyword like this:

policy_type = "allow"|"deny"
operations = [<operations-list>]
reasons = [<reasons-list>]
resources = [<resources-list>]


  • operations-list is a comma-separated list of one or more of these values or "*" to indicate that all operations are included:

    • "read"
    • "write"
    • "delete"
    • "search"
    • "tokenize"
    • "detokenize"
    • "encrypt"
    • "decrypt"
    • "hash"
    • "stats"
  • reasons-list is a comma-separated list of one or more of these values or "*" to indicate that all reasons are included:

    • AppFunctionality
    • Analytics
    • Notifications
    • Marketing
    • ThirdPartyMarketing
    • FraudPreventionSecurityAndCompliance
    • AccountManagement
    • Maintenance
    • DataSubjectRequest
    • Other, used when an ad-hoc reason is specified.
  • resources-list is a comma-separated list of one or more resources:

    • builtin data types specified as <collection–name>/types/<type-name>, <type-name> must be in uppercase.
    • properties specified as <collection–name>/properties/<property–name>.
    • transformations specified as <collection–name>/transformations/<transformation–name>.
    • tokens specified as <collection–name>/tokens.
    • archived items specified as <collection–name>/archived/[properties|tokens][/<property–name>].

    <collection–name>, <type-name>, <property–name>, or |<transformation–name>] can be specified as "*" to indicate that all collections, data types, properties, or transformations are included.

    For example:

    • "buyers/types/EMAIL" refers to the all the properties in the buyers collection based on the EMAIL data type.
    • "employees/properties/email" refers to the email property of the employees collection.
    • "*/properties/email" refers to the email property in any collection.
    • "customers/transformations/ssn.mask" refers to the mask transformation of the ssn property of the customers collection.
    • "*/tokens" refers to tokens in any collection.
    • "customers/archived/*" refers to any property of archived objects in the customers collection.


This example shows the specification of:

  • A CollectionsManager user.
  • A CollectionsReaderWriter role. The CollectionsReaderWriter role has the capabilities to enable it to maintain the schema of collections.
  • Two policies allowing read and write for all properties and transformations for any reason.

role = "CollectionsReaderWriter"


capabilities = ["CapCollectionsReader", "CapCollectionsWriter"]
policies = ["PolReadAll","PolWriteAll"]


policy_type = "allow"
operations = ["read"]
reasons = ["*"]
resources = ["*"]

policy_type = "allow"
operations = ["write"]
reasons = ["*"]
resources = ["*"]

On this page