Secret Store

Template for modeling secret storage systems with vaults, entries, and permissions

Secret Store is an Early Access feature. Contact your Veza account team to enable it for your organization.

Use this template to model secret and credential management systems using the Open Authorization API. The Secret Store template captures the authorization relationships for custom or self-hosted credential management systems that are not covered by a native Veza integration.

The template models a hierarchical structure:

• Secret Store - the top-level entity representing the secret management system instance

  • Permissions - define actions that identities can perform (e.g., Read, Write, Decrypt)

  • Vaults - logical containers for secrets within the store

    • Entries - individual secrets or credentials within a vault

      • Identities - optional identity mappings linking the entry to external identities

• Identity-to-Permission Bindings - map identities to permissions on specific vaults

A custom property definition can define additional properties for the secret store, permissions, vaults, and entries.

To use the secret store template, set the template type to secret_store when creating a new data provider:

curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"MySecretStore","custom_template":"secret_store"}'

Sample Payloads

HashiCorp Vault Example

This example demonstrates a secret store with two vaults, permissions, vault entries with identity mappings, and identity-to-permission bindings.

{
  "secret_store_type": "hashicorp_vault",
  "custom_property_definition": {
    "secret_store_properties": {
      "environment": "STRING"
    },
    "permission_properties": {},
    "vault_properties": {
      "encryption_type": "STRING"
    },
    "entry_properties": {
      "rotation_enabled": "BOOLEAN"
    }
  },
  "secret_store": {
    "name": "Production Vault",
    "id": "prod-vault-001",
    "description": "Production environment secrets",
    "tags": [
      {
        "key": "department",
        "value": "engineering"
      }
    ],
    "custom_properties": {
      "environment": "production"
    },
    "permissions": [
      {
        "name": "Read",
        "id": "perm-read",
        "resource": "secrets/*",
        "allow_identity_assume": false
      },
      {
        "name": "Write",
        "id": "perm-write",
        "resource": "secrets/*",
        "allow_identity_assume": true
      }
    ],
    "secret_store_vaults": [
      {
        "name": "API Keys",
        "id": "vault-api-keys",
        "vault_type": "kv",
        "description": "API key storage",
        "tags": [
          {
            "key": "category",
            "value": "api-credentials"
          }
        ],
        "custom_properties": {
          "encryption_type": "AES-256"
        },
        "entries": [
          {
            "name": "Stripe API Key",
            "id": "entry-stripe",
            "description": "Stripe payment processing key",
            "custom_properties": {
              "rotation_enabled": true
            },
            "identities": [
              {
                "type": "OktaUser",
                "external_id": "[email protected]"
              }
            ]
          }
        ]
      },
      {
        "name": "Database Credentials",
        "id": "vault-db-creds",
        "vault_type": "kv",
        "description": "Database connection credentials",
        "custom_properties": {
          "encryption_type": "AES-256"
        },
        "entries": [
          {
            "name": "PostgreSQL Admin",
            "id": "entry-postgres",
            "description": "PostgreSQL admin credentials",
            "custom_properties": {
              "rotation_enabled": true
            }
          }
        ]
      }
    ],
    "identity_to_permissions": [
      {
        "identity": "admin-user",
        "identity_type": "local_user",
        "permission_assignments": [
          {
            "vault": [
              "vault-api-keys",
              "vault-db-creds"
            ],
            "permissions": [
              "Read",
              "Write"
            ]
          }
        ]
      },
      {
        "identity": "developer-user",
        "identity_type": "local_user",
        "permission_assignments": [
          {
            "vault": [
              "vault-api-keys"
            ],
            "permissions": [
              "Read"
            ]
          }
        ]
      }
    ]
  }
}

Example: Custom PAM Integration

Organizations with custom or self-hosted privileged access management (PAM) systems can use the Secret Store template to model their credential vaults, entries, and access permissions. This example shows how to map a typical PAM structure to the Secret Store template.

Custom PAM Payload

This payload models a custom PAM system with two credential vaults, permission definitions, and identity-to-permission mappings reflecting typical DBA and platform engineer access patterns.

{
  "secret_store_type": "custom_pam",
  "custom_property_definition": {
    "vault_properties": {
      "rotation_policy": "STRING",
      "requires_approval": "BOOLEAN"
    },
    "entry_properties": {
      "credential_type": "STRING"
    }
  },
  "secret_store": {
    "name": "ACME Internal PAM",
    "id": "pam.acme-internal.example.com",
    "description": "Production internal credential management system",
    "tags": [
      {
        "key": "environment",
        "value": "production"
      }
    ],
    "permissions": [
      {
        "name": "View",
        "id": "perm-view",
        "allow_identity_assume": false
      },
      {
        "name": "Checkout",
        "id": "perm-checkout",
        "allow_identity_assume": true
      },
      {
        "name": "Rotate",
        "id": "perm-rotate",
        "allow_identity_assume": false
      },
      {
        "name": "Manage",
        "id": "perm-manage",
        "allow_identity_assume": false
      }
    ],
    "secret_store_vaults": [
      {
        "name": "Production Databases",
        "id": "vault-prod-databases",
        "vault_type": "database",
        "description": "Privileged database credentials for production systems",
        "custom_properties": {
          "rotation_policy": "30-day",
          "requires_approval": true
        },
        "entries": [
          {
            "name": "postgres-prod-admin",
            "id": "cred-pg-admin-001",
            "description": "PostgreSQL production superuser",
            "custom_properties": {
              "credential_type": "service_account"
            },
            "identities": [
              {
                "type": "AzureADUser",
                "external_id": "[email protected]"
              }
            ]
          },
          {
            "name": "mysql-prod-readonly",
            "id": "cred-mysql-ro-001",
            "description": "MySQL production read-only service account",
            "custom_properties": {
              "credential_type": "service_account"
            }
          }
        ]
      },
      {
        "name": "Cloud Platform Keys",
        "id": "vault-cloud-keys",
        "vault_type": "cloud_credentials",
        "description": "Cloud provider access keys",
        "custom_properties": {
          "rotation_policy": "90-day",
          "requires_approval": false
        },
        "entries": [
          {
            "name": "cloud-prod-admin",
            "id": "cred-cloud-admin-001",
            "description": "Production cloud IAM admin access key",
            "custom_properties": {
              "credential_type": "access_key"
            },
            "identities": [
              {
                "type": "AzureADUser",
                "external_id": "[email protected]"
              }
            ]
          }
        ]
      }
    ],
    "identity_to_permissions": [
      {
        "identity": "[email protected]",
        "identity_type": "AzureADUser",
        "permission_assignments": [
          {
            "vault": ["vault-prod-databases"],
            "permissions": ["View", "Checkout"]
          }
        ]
      },
      {
        "identity": "[email protected]",
        "identity_type": "AzureADUser",
        "permission_assignments": [
          {
            "vault": ["vault-cloud-keys"],
            "permissions": ["View", "Checkout", "Rotate"]
          },
          {
            "vault": ["vault-prod-databases"],
            "permissions": ["View"]
          }
        ]
      }
    ]
  }
}

This example demonstrates key patterns for working with the template:

• Vaults group credentials by scope. Permissions are granted at the vault level. Grouping credentials by team or system (databases, cloud keys) is the natural unit of access control.

• allow_identity_assume indicates whether this permission grants the ability to retrieve and use a credential's actual value.

• rotation_policy and requires_approval** are custom properties that capture PAM-specific policies useful for access reviews and compliance reporting.

Top-Level Payload

Field	Type	Description
secret_store_type	string	Type descriptor for the secret store (e.g., hashicorp_vault). Applied as a searchable property
custom_property_definition	object	Defines custom properties for the store, permissions, vaults, and entries. See Custom Properties
secret_store	object	The secret store object containing all entities
identity_mapping_configuration	object	Optional configuration for mapping local identities to users from external data sources
incremental_change	boolean	When true, enables incremental updates (optional)

Secret Store

The secret store object is the top-level container for permissions, vaults, and identity mappings.

"secret_store": {
  "name": "Production Vault",
  "id": "prod-vault-001",
  "description": "Production environment secrets",
  "tags": [],
  "custom_properties": {},
  "permissions": [],
  "secret_store_vaults": [],
  "identity_to_permissions": []
}

Secret Store Properties

Field	Type	Description
name	string	Display name for the secret store
id	string	Unique identifier. Defaults to name if not provided
description	string	Description shown in Veza entity details (optional)
tags	array	Specify tags with a key and optional value
custom_properties	dictionary	Custom Properties validated against the custom_property_definition
operation	string	Operation type for incremental updates (optional)
permissions	array	Array of permission objects
secret_store_vaults	array	Array of vault objects
identity_to_permissions	array	Array of identity-to-permission mappings

Permissions

Permissions define the actions that identities can perform on the secret store and its vaults. Permissions are referenced by name in identity-to-permission bindings.

"permissions": [
  {
    "name": "Read",
    "id": "perm-read",
    "resource": "secrets/*",
    "allow_identity_assume": false
  }
]

Permission Properties

Field	Type	Description
name	string	Display name for the permission
id	string	Unique identifier. Defaults to name if not provided
resource	string	Resource path or pattern this permission applies to (optional)
allow_identity_assume	boolean	Whether this permission allows identity assumption (optional)
tags	array	Specify tags with a key and optional value
custom_properties	dictionary	Custom Properties
operation	string	Operation type for incremental updates (optional)

Vaults

Vaults are logical containers for secrets within the store. Each vault has a type and can contain multiple entries.

"secret_store_vaults": [
  {
    "name": "API Keys",
    "id": "vault-api-keys",
    "vault_type": "kv",
    "description": "API key storage",
    "tags": [],
    "custom_properties": {},
    "entries": []
  }
]

Vault Properties

Field	Type	Description
name	string	Display name for the vault
id	string	Unique identifier. Defaults to name if not provided
vault_type	string	Type descriptor for the vault (e.g., kv, transit, pki). Required
description	string	Description shown in Veza entity details (optional)
tags	array	Specify tags with a key and optional value
custom_properties	dictionary	Custom Properties validated against the custom_property_definition
operation	string	Operation type for incremental updates (optional)
entries	array	Array of vault entry objects

Vault Entries

Entries represent individual secrets or credentials within a vault. Entries optionally include identity mappings that link the credential to external identities in the authorization graph.

"entries": [
  {
    "name": "Stripe API Key",
    "id": "entry-stripe",
    "description": "Stripe payment processing key",
    "custom_properties": {
      "rotation_enabled": true
    },
    "identities": [
      {
        "type": "OktaUser",
        "external_id": "[email protected]"
      }
    ]
  }
]

Vault Entry Properties

Field	Type	Description
name	string	Display name for the entry
id	string	Unique identifier. Defaults to name if not provided
description	string	Description shown in Veza entity details (optional)
tags	array	Specify tags with a key and optional value
custom_properties	dictionary	Custom Properties validated against the custom_property_definition
operation	string	Operation type for incremental updates (optional)
identities	array	Array of identity mapping objects (optional)

Vault Entry Identities

Identity mappings on vault entries link a credential to external identities in the authorization graph. When the payload is parsed, Veza creates graph edges between the vault entry and the referenced identities. See Custom Identity Mappings for more information.

"identities": [
  {
    "type": "OktaUser",
    "external_id": "[email protected]"
  }
]

Identity Properties

Field	Type	Description
type	string	The type of external identity (e.g., OktaUser, AzureADUser, AWSIAMUser)
external_id	string	The external identifier for the identity (e.g., email address, ARN)

Identity to Permissions

Identity-to-permission mappings define which identities have which permissions on which vaults. Each mapping links an identity to one or more permission assignments.

"identity_to_permissions": [
  {
    "identity": "admin-user",
    "identity_type": "local_user",
    "permission_assignments": [
      {
        "vault": ["vault-api-keys", "vault-db-creds"],
        "permissions": ["Read", "Write"]
      }
    ]
  }
]

Identity-to-Permission Properties

Field	Type	Description
identity	string	The identity ID or name
identity_type	string	The type of identity (e.g., local_user)
permission_assignments	array	Array of permission assignment objects

Permission Assignments

Each permission assignment binds a set of permissions to a set of vaults for the parent identity.

Field	Type	Description
vault	array	List of vault IDs or names that this assignment applies to
permissions	array	List of permission names granted to the identity on these vaults

Custom Property Definitions

Custom properties allow you to attach additional metadata to secret store entities. Define properties in the custom_property_definition object, then set values on individual entities.

"custom_property_definition": {
  "secret_store_properties": {
    "environment": "STRING"
  },
  "permission_properties": {},
  "vault_properties": {
    "encryption_type": "STRING"
  },
  "entry_properties": {
    "rotation_enabled": "BOOLEAN"
  }
}

Scope	Description
secret_store_properties	Custom properties for the secret store entity
permission_properties	Custom properties for permission entities
vault_properties	Custom properties for vault entities
entry_properties	Custom properties for vault entry entities

Property values must match their declared type. Supported types are described in Custom Properties.

Incremental Updates

After the initial metadata push (which must contain the full payload), you can modify, add, or remove the secret store, permissions, vaults, entries, and identity assignments without resubmitting other entities. An incremental update is enabled by setting "incremental_change": true in the push payload, and specifying the update operation for each entity to change.

Creating and Updating a Secret Store

To create the OAA provider and push data:

1. Create the provider with the secret_store template type:

   curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
   -H "authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
   --data '{"name":"MySecretStore","custom_template":"secret_store"}'

2. Create a data source on the provider:

   curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
   -H "authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
   --data '{"name":"my_secret_store_source"}'

3. Push the payload to the data source:

   curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
   -H "authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
   --data "{\"json_data\": $(jq -Rs . payload.json)}"

   The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs . reads payload.json and escapes it as a JSON string.

Updates follow the same push workflow. Veza processes the full payload and updates the Authorization Graph accordingly.