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 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:
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.
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.
The secret store object is the top-level container for permissions, vaults, and identity mappings.
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.
Vaults are logical containers for secrets within the store. Each vault has a type and can contain multiple entries.
Entries represent individual secrets or credentials within a vault. Entries optionally include that link the credential to external identities in the authorization graph.
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 for more information.
Identity-to-permission mappings define which identities have which permissions on which vaults. Each mapping links an identity to one or more permission assignments.
Each permission assignment binds a set of permissions to a set of vaults for the parent identity.
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.
Property values must match their declared type. Supported types are described in .
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 is enabled by setting "incremental_change": true in the push payload, and specifying the update operation for each entity to change.
To create the OAA provider and push data:
Create the provider with the secret_store template type:
Create a data source on the provider:
Push the payload to the data source:
The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs .
Updates follow the same push workflow. Veza processes the full payload and updates the Authorization Graph accordingly.
payload.jsoncurl -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"}'secret_store_type
string
Type descriptor for the secret store (e.g., hashicorp_vault). Applied as a searchable property
custom_property_definition
object
"secret_store": {
"name": "Production Vault",
"id": "prod-vault-001",
"description": "Production environment secrets",
"tags": [],
"custom_properties": {},
"permissions": [],
"secret_store_vaults": [],
"identity_to_permissions": []
}name
string
Display name for the secret store
id
string
"permissions": [
{
"name": "Read",
"id": "perm-read",
"resource": "secrets/*",
"allow_identity_assume": false
}
]name
string
Display name for the permission
id
string
"secret_store_vaults": [
{
"name": "API Keys",
"id": "vault-api-keys",
"vault_type": "kv",
"description": "API key storage",
"tags": [],
"custom_properties": {},
"entries": []
}
]name
string
Display name for the vault
id
string
"entries": [
{
"name": "Stripe API Key",
"id": "entry-stripe",
"description": "Stripe payment processing key",
"custom_properties": {
"rotation_enabled": true
},
"identities": [
{
"type": "OktaUser",
"external_id": "alice@example.com"
}
]
}
]name
string
Display name for the entry
id
string
"identities": [
{
"type": "OktaUser",
"external_id": "alice@example.com"
}
]type
string
The type of external identity (e.g., OktaUser, AzureADUser, AWSIAMUser)
external_id
string
"identity_to_permissions": [
{
"identity": "admin-user",
"identity_type": "local_user",
"permission_assignments": [
{
"vault": ["vault-api-keys", "vault-db-creds"],
"permissions": ["Read", "Write"]
}
]
}
]identity
string
The identity ID or name
identity_type
string
vault
array
List of vault IDs or names that this assignment applies to
permissions
array
"custom_property_definition": {
"secret_store_properties": {
"environment": "STRING"
},
"permission_properties": {},
"vault_properties": {
"encryption_type": "STRING"
},
"entry_properties": {
"rotation_enabled": "BOOLEAN"
}
}secret_store_properties
Custom properties for the secret store entity
permission_properties
Custom properties for permission entities
vault_properties
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"}'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"}'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)}"Defines custom properties for the store, permissions, vaults, and entries. See
secret_store
object
The 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 (optional)
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
validated against the custom_property_definition
operation
string
Operation type for (optional)
permissions
array
Array of objects
secret_store_vaults
array
Array of objects
identity_to_permissions
array
Array of mappings
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
operation
string
Operation type for (optional)
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
validated against the custom_property_definition
operation
string
Operation type for (optional)
entries
array
Array of objects
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
validated against the custom_property_definition
operation
string
Operation type for (optional)
identities
array
Array of objects (optional)
The external identifier for the identity (e.g., email address, ARN)
The type of identity (e.g., local_user)
permission_assignments
array
Array of objects
List of permission names granted to the identity on these vaults
Custom properties for vault entities
entry_properties
Custom properties for vault entry entities
{
"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": "alice@example.com"
}
]
}
]
},
{
"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"
]
}
]
}
]
}
}{
"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": "dba-admin@acme.com"
}
]
},
{
"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": "platform-eng@acme.com"
}
]
}
]
}
],
"identity_to_permissions": [
{
"identity": "dba-admin@acme.com",
"identity_type": "AzureADUser",
"permission_assignments": [
{
"vault": ["vault-prod-databases"],
"permissions": ["View", "Checkout"]
}
]
},
{
"identity": "platform-eng@acme.com",
"identity_type": "AzureADUser",
"permission_assignments": [
{
"vault": ["vault-cloud-keys"],
"permissions": ["View", "Checkout", "Rotate"]
},
{
"vault": ["vault-prod-databases"],
"permissions": ["View"]
}
]
}
]
}
}Template for setting custom property values on existing entities in the Veza authorization graph
Use this template to set custom property values on existing entities in the Veza authorization graph using the Open Authorization API. Unlike other OAA templates that create new entities, the Entity Enrichment template adds metadata to entities that already exist from other integrations.
Entity enrichment is useful when you have supplemental data about entities that Veza already discovers through native integrations. For example, you might enrich AWS IAM roles with internal compliance metadata, or tag Okta users with cost center information from a custom source.
The template has two sections:
Enriched entity property definitions - declares the custom properties and their types for each entity type being enriched.
Enriched entities - the list of existing entities to enrich, with values for each declared property.
To use the entity enrichment template, set the template type to entity_enrichment when creating a new data provider:
Each entry declares the custom properties that will be added to a specific entity type, along with their data types. Property types determine how Veza stores and indexes values. For example, TIMESTAMP properties enable relative date filters in queries (such as "last 90 days").
The list of existing entities to enrich with property values. Each entity must appear exactly once with all properties that should be set. Including an entity with no properties clears all enriched property values from that entity. Only entities in the list are updated; other entities are not affected.
To create the OAA provider and push enrichment data:
Create the provider with the entity_enrichment template type:
Create a data source on the provider:
Push the enrichment payload to the data source:
The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs .
Updates follow the same push workflow. Each push replaces the enrichment data for the entities included in the payload. Entities not included in the push are not affected.
Property values vs. property definitions: You can clear a property value by omitting its key in a subsequent push, or by including the entity with an empty properties object. This clears the stored value but does not remove the property definition from the entity type. Once a property name is defined for an entity type, the definition persists in the graph and cannot be removed.
Provider deletion: Deleting an enrichment provider does not remove enrichment data from the Veza graph. Data pushed through the provider remains associated with the enriched entities after the provider is deleted. Contact Veza support if you need to fully remove enrichment data from the graph.
payload.jsoncurl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"My Enrichment Provider","custom_template":"entity_enrichment"}'enriched_entity_property_definitions
array
List of for each entity type
enriched_entities
array
"enriched_entity_property_definitions": [
{
"entity_type": "AwsIamRole",
"enriched_properties": {
"my_company_id": "STRING",
"is_compliance_validated": "BOOLEAN"
}
}
]entity_type
string
Veza entity type to enrich (e.g., AwsIamRole, OktaUser)
enriched_properties
dictionary
STRING
Text value
NUMBER
Numeric value (integer or float)
BOOLEAN
"enriched_entities": [
{
"type": "AwsIamRole",
"id": "arn:aws:iam::339083562601:role/Administrator",
"data_source_id": "339083562601:awsiam",
"properties": {
"my_company_id": "DCFB16CD-A044-4787-9165-1C926221F887",
"is_compliance_validated": true
}
}
]type
string
Veza entity type (must match an entity_type in the property definitions)
id
string
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"Enrichment Provider","custom_template":"entity_enrichment"}'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":"Enrichment 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)}"List of entities to enrich with property values
Map of property names to their types. See supported types
true or false
TIMESTAMP
Date/time value. Enables relative date filters in Veza queries
STRING_LIST
List of string values
Veza unique ID for the entity. For AWS entities, this is the ARN. Each entity must appear only once in the list
data_source_id
string
Veza data source ID for the entity. For AWS, combine the account ID with the data source type (e.g., 339083562601:awsiam)
properties
dictionary
Map of property names to values. Keys must be defined in the property definitions, and values must match the declared type. Omitting a key that is defined in the property definitions removes that property value from the entity
{
"enriched_entity_property_definitions": [
{
"entity_type": "AwsIamRole",
"enriched_properties": {
"my_company_id": "STRING",
"company_purpose": "STRING",
"is_compliance_validated": "BOOLEAN"
}
},
{
"entity_type": "AwsIamUser",
"enriched_properties": {
"company_purpose": "STRING"
}
}
],
"enriched_entities": [
{
"type": "AwsIamRole",
"id": "arn:aws:iam::339083562601:role/Administrator",
"data_source_id": "339083562601:awsiam",
"properties": {
"my_company_id": "DCFB16CD-A044-4787-9165-1C926221F887",
"company_purpose": "Built in Admin role",
"is_compliance_validated": true
}
},
{
"type": "AwsIamRole",
"id": "arn:aws:iam::650251689811:role/andrew_s3_all",
"data_source_id": "339083562601:awsiam",
"properties": {
"my_company_id": "A3F40BAC-1871-4EFC-A0EE-CD77E3F513C27",
"company_purpose": "Some role for Andrew",
"is_compliance_validated": false
}
},
{
"type": "AwsIamUser",
"id": "arn:aws:iam::339083562601:user/andrew",
"data_source_id": "339083562601:awsiam",
"properties": {
"company_purpose": "Engineering service account"
}
}
]
}JSON schemas for describing custom applications, identity providers, principals, and secret stores
OAA utilizes templates (JSON schema) for structuring authorization and identity metadata, combined with a REST API to register, update and manage the data. Once uploaded, Veza processes the template payload and incorporates the entities and permissions into the Authorization Metadata Graph.
Choosing the appropriate template is the first step in creating a new integration with OAA. The template provides a schema for describing the identities, resources, and authorization relationships local to the OAA data source.
For most applications, SaaS Apps and systems the Custom Application Template provides a generic and flexible model to capture authorization data for users and groups to the system and its resources.
A custom application is structured with the following main entities:
Application
Resource
Sub-resource
Sub-resource
Local Permissions
Identity-to-permissions binding
Intended for modeling sources of users, group, and federated identity metadata, the can be used to enumerate users and groups that access other external applications and resources, similar to built-in connectors for Okta and AzureAD. These users and groups typically represent the top-level corporate identities within an organization.
A Custom Identity Provider can have the following entities:
Domains
Users
Groups
The Custom IdP template also includes the option to define AWS Roles that are assumable by users and groups and can work with Access Review Workflows to auto-assign resource managers.
For modeling sources of identities (users, groups, and tenants) that connect to other OAA data sources on the same provider, the provides a lightweight identity model. Unlike the Custom IdP, which models a full identity provider with domains, the Principal template is designed to feed users and groups into Custom Application or other templates on the same provider.
A Custom Principal is structured with:
Tenant
Users
Groups
For modeling secret and credential management systems, the captures vaults, entries, permissions, and identity access mappings. Use this template to connect custom or self-hosted credential management systems that are not covered by a native Veza integration.
A Secret Store is structured with:
Secret Store
Permissions
Vaults
Entries
The adds custom property values to entities that already exist in the Veza authorization graph from other integrations. Use this template to attach supplemental metadata (such as compliance status, cost center, or internal identifiers) to entities discovered by native integrations.
An Entity Enrichment submission contains:
Enriched entity property definitions (schema declarations)
Enriched entities (entity references with property values)
Template for pushing IdP domain, user, and group metadata
Use this template to model authorization metadata for custom identity providers using the .
This document includes an example template and notes for designing and a model of your IdP.
Local Users
Local Groups
Local Roles
Identities
Identity-to-Permission Bindings
A custom property definition can define additional properties, used to add supplemental metadata to entities in the payload.
Veza will handle federated identities just as those in supported IdPs such as Okta or Entra ID, enabling search and access review for OAA entities alongside the rest of your data catalog.
The metadata payload describes the Identity Provider domain, users, and groups to add to the Veza Access Graph:
For cases where federated IdP entities are granted AWS permissions via IAM roles, the template supports defining assumable roles per-user. Binding a custom IdP user or group to an AWS role or group ARN enables Veza to parse and display the resource-level actions permitted within AWS.
Custom IdP users and groups can be assigned permissions in other OAA applications by setting the principal type to idp in identity_to_permissions in the custom application payload.
For use cases where a custom IdP is federated with another identity provider user identities can be linked between the two. Authorizations granted to the user will also be granted the source identity. The link is created by providing the unique identity ID and provider type as part of the user entry.
For provider_type the following values are accepted:
Provider
provider_type string
Active Directory
active_directory
Any
any
Azure AD
New in Veza release
2022.2.1
To assign an IdP user or group as the manager of any resource Veza has discovered, list the node type and node id in the entities_owned field, for example:
When parsing the payload, resources in the data catalog will be updated with a SYSTEM_resource_managers tag to enable entitlement reviews. The owner(s) will be suggested as reviewers for Veza Workflows that target an individual named resource with the correct tag.
Users and groups can be mapped to the identity of another user they report to. When configured, the manager will be suggested as a review for Workflow certifications where the assigned reporter is the single query target "named entity."
Custom Properties are the recommended method for adding additional metadata to custom identities and resources.
The custom_property_definition object supports separate property namespaces for each entity type:
domain_properties
Custom property definitions for IdP domain entities.
user_properties
Custom property definitions for IdP user entities.
group_properties
Additionally, Veza tags can be applied to the IdP domain, users, and groups:
Use incremental updates to remove tags: Resubmitting a payload with different tags will apply any new tags, but not remove existing ones. To remove a tag already applied to an entity, you will need to use the incremental update remove_tag operation.
After the initial metadata push (which must contain the full payload), you can modify, add, or remove the domain, users, and groups without resubmitting other entities. An incremental update is enabled by setting "incremental_change": true in the json_data push payload, and specifying the update operation for each entity to change.
The identity provider object models one instance of the custom IdP:
name
string
Name to associate with the provider in Veza.
custom_property_definition
One domain is supported for each custom IdP. Users and groups are mapped to the IdP domain, and connected in Veza Search:
name
string
IdP Domain name
custom_properties
Each IdP user object contains the display name, login email, and identity, along with other identity-related properties:
name
string
Primary ID for user
email
Add a group by name in the groups section of the template to enable mapping IdP users to those groups:
name
string
IdP group name.
identity
string
IdP entities can be granted permissions on custom applications in the
identity_to_permissionssection of the custom app metadata payload.
Use the apps section to define any applications used to manage access within the identity provider. Apps can be associated with users and groups to model application assignments across your organization.
id
string
App unique identifier.
name
string
The apps payload does not accept an owners field. To assign owners to CustomIDPApp entities, see Supported entity types for owner assignment.
Users and Groups can be assigned to an application by setting the app_assignments in the user or group.
id
string
Assignment unique identifier.
name
string
The steps to add a custom IdP are the same as for any other OAA provider: you will need to register the new provider and data source, and then push the domain, user, and group descriptions in a JSON payload.
To create a new custom provider using the identity_provider template, POST the name and template type to /providers/custom:
The response will return the custom IdP ID, which you will need when pushing the metadata payload:
Note that the provider id is required in both the path and body of the request. The response will include the new data source ID.
The payload file must contain the provider and data source ID, and the authorization metadata as a single string, for example:
The identity_mapping_configuration parameter defines rules for connecting users in a custom IdP to users from other data sources in the Veza graph.
This is useful when:
The connected data source does not natively support returning information about external identities
A correlation between IdP identities and local users can be assumed based on values like username, email, or another property value.
The identity_mapping_configuration is a top-level property of the Custom IDP submission, and is optional. The mapping configuration can include multiple mappings to connect IDP users to users from different data source types,
each based on its own mappings.
You can update just the identity mappings without resubmitting the entire provider payload by using an incremental update. This is useful when you need to modify only the mapping configuration while leaving other provider data unchanged.
Example curl command to apply the incremental identity mapping update:
mappings
IdentityMappingSubmission
List of mappings to create between IDP Users and external data sources
operation
enum
destination_datasource_type
string
Veza Type for the destination data source, GITHUB_USERS, SQL_SERVER, CUSTOM_APPLICATION
destination_datasource_oaa_app_type
string
Supported transformations:
IGNORE_SPECIAL: Ignore special characters (_, -, .) when matching identities
IGNORE_DOMAIN: Match identities after removing domain portions (e.g., "@example.com")
source_property
enum
IdP User property to match on: UNIQUE_ID, EMAIL, PROPERTY, CUSTOM_PROPERTY, or TEMPLATE
destination_property
enum
Set source_property or destination_property to TEMPLATE to match on a constructed value instead of a single property, and put the expression in the corresponding custom_source_property or custom_destination_property field. For example, {FirstInitial | LOWER}{LastName | LOWER} matches a user named John Doe against jdoe. Veza validates the expression when you submit the payload and rejects unknown transformation functions. For the available properties and functions, see Template Transformations.
{
"name": "Custom User",
"assumed_role_arns": {
"identity": [
"arn:aws:iam::123456789012:role/S3Access"
]
},
}{
"name": "Custom User",
"identity": "00001",
"source_identity": {
"identity": "user0001@corp.example.com",
"provider_type": "okta"
}
}{
"name": "Custom User",
"identity": "000011",
"entities_owned": [
{
"node_type": "S3Bucket",
"id": "arn:aws:s3:::amazon-connect-53f87966654d"
}
]
}{
"name": "Custom User",
"identity": "000013",
"manager_id": "000011"
}"tags": [
{
"key": "Tag1key",
"value": "optional_Tag1Val"
}
]{
"name": "willis",
"email": "willis@example.com",
"identity": "000001",
"full_name": "Charles Willis",
"department": "Sales",
"is_active": true,
"is_guest": false,
"groups": [
{
"identity": "everyone"
}
],
"assumed_role_arns": {
"identity": [
"arn:aws:iam::123456789012:role/S3Access"
]
},
"source_identity": {
"identity": "user0001@corp.example.com",
"provider_type": "okta"
},
"tags": [],
"custom_properties": {},
"manager_id": "string",
"entities_owned": {
"node_type": "S3Bucket",
"id": "arn:aws:s3:::amazon-connect-53f87966654d"
}
}"groups": [
{
"name": "developers",
"identity": "developers",
"full_name": null,
"is_security_group": null,
"assumed_role_arns": {
"identity": ["arn:aws:iam::123456789012:role/S3Access"]
},
"tags": [],
"groups": [
{ "group_1_identity": "parent" },
{ "group_2_identity": "parent" }
],
"custom_properties": {}
}
] "apps": [
{
"id": "app1",
"name": "Application 1",
"description": "This is a sample application",
"assumed_role_arns": [
{
"identity": "arn:aws:iam::1234567890:role/DevAppRole"
}
],
"custom_properties": {
"owner_org": "engineering"
},
"tags": []
}
] {
"name": "willis",
"email": "willis@example.com",
"identity": "cwilliams",
"groups": [
{
"identity": "everyone"
}
],
"custom_properties": {
"region": "NorthAmerica",
"is_contractor": true
},
"app_assignments": [
{
"id": "assignment1",
"name": "Assignment",
"app_id": "app1",
"custom_properties": {
"assigned_on": "2024-12-05T12:42:25+00:00"
}
}
]
}curl -X POST 'https://<veza_url>/api/v1/providers/custom' \
-H 'authorization: Bearer '<access_token> \
--data-binary '{"name":"SimpleIdP","custom_template":"identity_provider"}'{
"value": {
"id": "532f6fe3-189f-4576-afdf-8913088961e4",
"name": "Simple IdP",
"custom_template": "identity_provider",
"state": "ENABLED",
"application_types": [],
"resource_types": [],
"idp_types": []
}
}curl -X POST 'https://<veza_url>/api/v1/providers/custom/532f6fe3-189f-4576-afdf-8913088961e4/datasources' \
-H 'authorization: Bearer '<access_token> \
--data-binary '{"id":"532f6fe3-189f-4576-afdf-8913088961e4", "name":"SimpleDataSource"}'{"value":{"id":"b6a32af6-b854-47e1-8325-e5984f78bb4d","name":"SimpleDataSource"}}curl -X POST 'https://<veza_url>/api/v1/providers/custom/532f6fe3-189f-4576-afdf-8913088961e4/datasources/b6a32af6-b854-47e1-8325-e5984f78bb4d:push' \
-H 'authorization: Bearer '<access_token> \
--compressed --data-binary @payload.json{
"id": "532f6fe3-189f-4576-afdf-8913088961e4",
"data_source_id": "b6a32af6-b854-47e1-8325-e5984f78bb4d",
"json_data": "{\n\"name\":\"CustomIdentityProvider\",\n\"idp_type\": ... "
}{
"identity_mapping_configuration": {
"mappings": [
{
"destination_datasource_type": "OKTA",
"property_matchers": [
{
"source_property": "EMAIL",
"destination_property": "EMAIL"
}
],
"transformations": [
"IGNORE_SPECIAL"
]
},
{
"destination_datasource_type": "AZURE_AD",
"property_matchers": [
{
"source_property": "EMAIL",
"destination_property": "EMAIL"
}
],
"transformations": [
"IGNORE_DOMAIN"
]
},
{
"destination_datasource_type": "GITHUB_USERS",
"property_matchers": [
{
"source_property": "EMAIL",
"destination_property": "UNIQUE_ID"
}
]
}
]
}
}curl --location 'https://<veza_url>/api/v1/providers/custom/816d6e51-6d6a-4279-ba41-2e7c732be880/datasources/716026b5-4b84-4b2f-a805-b41a6ec69cf3:push' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data '{
"id": "816d6e51-6d6a-4279-ba41-2e7c732be880",
"data_source_id": "716026b5-4b84-4b2f-a805-b41a6ec69cf3",
"json_data": "{\"incremental_change\":true,\"identity_mapping_configuration\":{\"operation\":\"modify\",\"mappings\":[{\"destination_datasource_type\":\"GITHUB_USERS\",\"property_matchers\":[{\"source_property\":\"EMAIL\",\"destination_property\":\"UNIQUE_ID\"}]},{\"destination_datasource_type\":\"SQL_SERVER\",\"property_matchers\":[{\"source_property\":\"EMAIL\",\"destination_property\":\"EMAIL\"}],\"transformations\":[\"IGNORE_DOMAIN\"]}]}}"
}'Property values are case-sensitive and must be uppercase. Veza resolves an unrecognized value to UNIQUE_ID without returning an error, so a lowercase email matches on unique ID instead of email address. The type, mode, and transformations fields are case-insensitive.
azure_ad
OAA
custom
Google Workspace
google_workspace
Okta
okta
One Login
one_login
Custom property definitions for IdP group entities.
app_properties
Custom property definitions for IdP app entities.
app_assignment_properties
Custom property definitions for app assignment entities.
Defines the key and types for properties that can be applied to other objects in the push payload
idp_type
string
Type descriptor for IdP, can be unique or share across multiple IdP (for example ldap, IPA)
idp_description
string
Any notes to add as entity details (optional)
domains
Domain model
users
Dictionary of CustomIdPUser class instances
groups
Dictionary of CustomIdPGroup class instances
incremental_change
boolean
When true, enables incremental update operations (optional).
identity_mapping_configuration
Configuration for mapping identities between IdP User and other User types from external data sources
Each element of the push payload can have property_values, validated against the custom_property_definition.
dynamic_properties
Dynamic Properties
Up to 5 attributes to apply to the domain (deprecated, use custom properties instead)
tags
Veza Tags list
Any tags to create and apply to the domain.
operation
enum
For incremental updates, the operation to use.
string
Optional email for user
identity
string
Optional unique identifier for user
groups
string list
Assign groups memberships by group identity (optional)
full_name
string
Full name to display in Veza
department
string
Department to apply as a searchable property (optional).
is_active
boolean
If available, will be applied to the entity as a searchable property (optional).
is_guest
boolean
If available, will be applied to the entity as a searchable property (optional).
assumed_role_arns
array
AWS IAM roles that can be assumed by the IdP user, in the format {"identity": ["arn:aws:iam::123456789012:role/S3Access"]} (optional).
tags
Veza Tags list
Any tags to create and apply to the user.
dynamic_properties
Dynamic Properties
Up to 5 attributes to apply to the user (deprecated, use custom properties instead)
custom_properties
Each element of the push payload can have property_values, validated against the custom_property_definition.
manager_id
string
If the same as another user's identity, that user will be recommended for access reviews. Entity details for the user will be updated on push to include the manager as a searchable property.
entities_owned
Entities Owned array
If another resource is specified by entity type and entity id, a Veza tag will be created on the resource to indicate the owner.
operation
enum
For incremental updates, the operation to use (optional).
source_identity
Optionally link IdP user to user from another IdP for federation use cases.
Unique ID used for user-group assignments.
full_name
string
Optional display name for group
groups
string list
other custom IdP groups this group is a member of
is_security_group
boolean
Sets the is security group searchable property for the entity in Veza (optional).
tags
Veza Tags list
Any tags to create and apply to the group.
custom_properties
Each element of the push payload can have property_values, validated against the custom_property_definition.
dynamic_properties
Dynamic Properties
Up to 5 attributes to apply to the domain. (deprecated, use custom properties instead)
operation
enum
For incremental updates, the operation to use (optional).
assumed_role_arns
array
AWS IAM roles the group can assume, in the format {"identity": ["arn:aws:iam::123456789012:role/S3Access"]} (optional).
source_identity
Optionally link the IdP group to a group from another IdP for federation use cases (optional).
entities_owned
Entities Owned array
Resources to assign this group as manager of (optional).
app_assignments
array
App assignments for this group (optional). See IdP Apps.
IdP app name.
description
string
Description for the App (optional).
assumed_role_arns
array
AWS IAM roles the app can assume, in the format {"identity": ["arn:aws:iam::123456789012:role/S3Access"]} (optional).
custom_properties
Each element of the payload can have property_values, validated against the custom_property_definition.
tags
Veza Tags list
Any tags to create and apply to the group.
operation
enum
For incremental updates, the operation to use (optional).
Display name for the assignment.
app_id
string
Unique ID of the App to assign the identity to.
custom_properties
Each element of the payload can have property_values, validated against the custom_property_definition.
For incremental updates, the operation to use.
Optional specifically for mapping to OAA Custom Application to provide a specific App Type
destination_datasources
list
Optional list of destinations for the mapping, each with a type and an optional oaa_app_type. Veza uses this list only when destination_datasource_type is empty; if destination_datasource_type is set, this list is ignored
mode
enum
Entities to connect: USERS (the default) connects IdP users to destination users, GROUPS connects IdP groups to destination groups, ROLE_TO_USER connects IdP roles to destination users
property_matchers
IdentityMappingPropertyMatchersSubmission
List of properties to match on
transformations
list enum
Optional transformations to perform on the property values, available values: ignore_special, ignore_domain
Destination User property to match on. Accepts the same values as source_property
custom_source_property
string
With PROPERTY or CUSTOM_PROPERTY, the source property name to match on. With TEMPLATE, the template expression to evaluate on the source
custom_destination_property
string
With PROPERTY or CUSTOM_PROPERTY, the destination property name to match on. With TEMPLATE, the template expression to evaluate
{
"name": "My IdP",
"idp_type": "custom_idp",
"domains": [
{
"name": "example.com",
"tags": [],
}
],
"users": [
{
"name": "m_richardson",
"email": "mrichardson@example.com",
"identity": "m_richardson",
"full_name": "Michelle Richardson",
"department": null,
"is_active": true,
"is_guest": false,
"groups": [
{
"identity": "everyone"
},
{
"identity": "developers"
}
],
"assumed_role_arns": [
{
"identity": "arn:aws:iam::123456789012:role/role001"
},
{
"identity": "arn:aws:iam::123456789012:role/role002"
}
],
"tags": [],
},
{
"name": "evargas",
"email": "evargas@example.com",
"identity": "evargas",
"full_name": "Elizabeth Vargas",
"department": null,
"is_active": true,
"is_guest": false,
"groups": [
{
"identity": "everyone"
},
{
"identity": "developers"
},
{
"identity": "sec-ops"
}
],
"assumed_role_arns": [],
"tags": [],
},
{
"name": "willis",
"email": "willis@example.com",
"identity": "c_williams",
"full_name": null,
"department": null,
"is_active": true,
"is_guest": false,
"groups": [
{
"identity": "everyone"
}
],
"assumed_role_arns": [],
"tags": []
}
],
"groups": [
{
"name": "developers",
"identity": "developers",
"full_name": null,
"is_security_group": null,
"tags": []
},
{
"name": "sec-ops",
"identity": "sec-ops",
"full_name": null,
"is_security_group": null,
"tags": []
},
{
"name": "everyone",
"identity": "everyone",
"full_name": "All Company Employees",
"is_security_group": null,
"tags": []
}
],
"identity_mapping_configuration": {
"mappings": [
{
"destination_datasource_type": "GITHUB_USERS",
"property_matchers": [
{
"source_property": "EMAIL",
"destination_property": "UNIQUE_ID"
}
]
},
{
"destination_datasource_type": "SQL_SERVER",
"property_matchers": [
{
"source_property": "EMAIL",
"destination_property": "EMAIL"
}
],
"transformations": [
"IGNORE_DOMAIN"
]
}
]
}
}{
"incremental_change": true,
"identity_mapping_configuration": {
"operation": "modify",
"mappings": [
{
"destination_datasource_type": "GITHUB_USERS",
"property_matchers": [
{
"source_property": "EMAIL",
"destination_property": "UNIQUE_ID"
}
]
},
{
"destination_datasource_type": "SQL_SERVER",
"property_matchers": [
{
"source_property": "EMAIL",
"destination_property": "EMAIL"
}
],
"transformations": [
"IGNORE_DOMAIN"
]
}
]
}
}Template for modeling a lightweight identity source with users, groups, and tenants
Use this template to model a source of identities (users, groups, and tenants) using the . Principals represent identity sources that connect to other OAA template types on the same provider, enabling Veza to map users and groups to the applications and resources they access.
The Custom Principal template differs from the in scope: a Principal is a lightweight identity source meant to feed users and groups into Custom Application or other templates on the same provider. Custom IdP models a full identity provider with domains and federated identity features.
The template has three primary entities:
Tenant - the top-level container for the principal instance. Each submission has exactly one tenant.
is_active, email, and timestamps.Groups - collections of users. Groups support hierarchical nesting through parent group references.
A custom property definition can define additional properties for tenants, users, and groups.
To use the principal template, set custom_templates to a list that includes principal when creating the provider. Because a principal is almost always used alongside an application, include both templates:
Then create a data source for the principal on that provider, specifying the principal template:
Veza's Atlassian Cloud connector uses the Custom Principal template to model the organization-level identity directory in Atlassian Cloud. The principal feeds users and groups into the Jira Cloud and Confluence Cloud application connectors on the same provider, linking identities to the resources they access.
This approach separates identity management (who exists, what products they can access) from application-level authorization (what permissions they have in Jira projects or Confluence spaces). The principal captures the organization directory, while separate Custom Application submissions model Jira and Confluence.
Key patterns from this integration:
user_type distinguishes managed users (in the organization's domain) from external collaborators, enabling access reviews to flag external access.
product_access as a STRING_LIST tracks which Atlassian products each user can access (Jira, Confluence, Bitbucket), providing visibility into license usage.
access_billable flags whether the user counts toward the organization's Atlassian license seat count.
Groups map to product access rather than organizational structure — groups like jira-software-users and confluence-users reflect Atlassian's product-based access model.
The principal connects to application templates on the same provider. Users and groups defined here appear as identities in Jira Cloud and Confluence Cloud Custom Application submissions, linking organization membership to application-level permissions.
name
string
Name of the principal provider instance
principal_type
string
Each principal submission contains exactly one tenant, representing the top-level container for the identity source.
name
string
Display name for the tenant
id
string
Users represent individual identities in the principal system. Each user can be linked to external identities and assigned to groups.
name
string
Display name for the user
id
Groups represent collections of users. Groups can have external identities and support hierarchical nesting through parent group references.
name
string
Display name for the group
id
string
Custom properties allow you to attach additional metadata to principal entities. Define properties in the custom_property_definition object, then set values on individual entities.
tenant_properties
Custom properties for the tenant entity
user_properties
Custom properties for user entities
group_properties
Property values must match their declared type. Supported types are described in Custom Properties.
After the initial metadata push (which must contain the full payload), you can modify, add, or remove the tenant, users, and groups 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.
To create the OAA provider and push data:
Create the provider with both the principal and application template types:
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"ExampleCorp","custom_templates":["principal","application"]}'Create a data source on the provider, specifying the principal template:
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":"Principal Data Source","custom_template":"principal"}'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.
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"ExampleCorp","custom_templates":["principal","application"]}'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":"Principal Data Source","custom_template":"principal"}'"tenant": {
"name": "Example Corp",
"id": "tenant-001",
"tenant_unique_id": "tenant-001",
"tags": [],
"custom_properties": {}
}"users": [
{
"name": "Alice Johnson",
"id": "alice01",
"email": "alice@example.com",
"user_unique_id": "alice01",
"display_name": "Alice Johnson",
"is_active": true,
"created_date": "2024-01-15T09:00:00.000Z",
"last_login": "2025-02-20T14:30:00.000Z",
"identities": ["alice@example.com"],
"groups": [{"id": "grp-engineering"}],
"tags": [],
"custom_properties": {}
}
]"groups": [
{
"name": "Engineering",
"id": "grp-engineering",
"group_unique_id": "grp-engineering",
"group_type": "Department",
"identities": ["engineering@example.com"],
"tags": [],
"custom_properties": {}
},
{
"name": "Platform Team",
"id": "grp-platform",
"group_type": "Team",
"parent_group": {
"id": "grp-engineering"
}
}
]"custom_property_definition": {
"tenant_properties": {
"region": "STRING"
},
"user_properties": {
"department": "STRING",
"mfa_enabled": "BOOLEAN"
},
"group_properties": {
"is_security_group": "BOOLEAN"
}
}Type descriptor for the principal provider (e.g., corporate_directory). Applied as a searchable property
custom_property_definition
object
Defines custom properties for tenants, users, and groups. See
tenant
object
The object for this principal
users
array
Array of objects
groups
array
Array of objects
incremental_change
boolean
When true, enables (optional)
Unique identifier for the tenant
tenant_unique_id
string
Optional unique identifier, typically a URL or external ID. Defaults to id if not provided
tags
array
Specify tags with a key and optional value
custom_properties
dictionary
validated against the custom_property_definition
operation
enum
For , the operation to apply (optional)
string
Unique identifier for the user. Defaults to name if not provided
email
string
Email address for the user (optional)
user_unique_id
string
Optional unique identifier. Defaults to email if set, otherwise id
display_name
string
Display name shown in Veza (optional)
is_active
boolean
Whether the user account is active
created_date
string
Date the user was created, in RFC 3339 format (e.g., 2024-01-15T09:00:00.000Z)
deactivated_date
string
Date the user was deactivated, in RFC 3339 format (optional)
last_login
string
Date of the user's last login, in RFC 3339 format (optional)
identities
array
List of identity strings (e.g., email addresses) used for linking to external identity providers
groups
array
List of group references as {"id": "group_id"} objects
tags
array
Specify tags with a key and optional value
custom_properties
dictionary
validated against the custom_property_definition
operation
enum
For , the operation to apply (optional)
Unique identifier for the group. Defaults to name if not provided
group_unique_id
string
Optional unique identifier for the group. Defaults to id if not provided
group_type
string
Type descriptor for the group (e.g., Security, Department, Team)
parent_group
object
Reference to a parent group as {"id": "parent_group_id"} for hierarchical nesting (optional)
identities
array
List of identity strings for linking to external identity providers
tags
array
Specify tags with a key and optional value
custom_properties
dictionary
validated against the custom_property_definition
operation
enum
For , the operation to apply (optional)
Custom properties for group entities
{
"custom_property_definition": {
"tenant_properties": {
"region": "STRING"
},
"user_properties": {
"department": "STRING",
"mfa_enabled": "BOOLEAN"
},
"group_properties": {
"is_security_group": "BOOLEAN"
}
},
"name": "Example Corp",
"principal_type": "corporate_directory",
"tenant": {
"name": "Example Corp",
"id": "tenant-001",
"tenant_unique_id": "tenant-001",
"tags": [
{
"key": "environment",
"value": "production"
}
],
"custom_properties": {
"region": "us-west-2"
}
},
"users": [
{
"name": "Alice Johnson",
"id": "alice01",
"email": "alice@example.com",
"user_unique_id": "alice01",
"display_name": "Alice Johnson",
"is_active": true,
"created_date": "2024-01-15T09:00:00.000Z",
"last_login": "2025-02-20T14:30:00.000Z",
"identities": [
"alice@example.com"
],
"groups": [
{
"id": "grp-engineering"
}
],
"custom_properties": {
"department": "Engineering",
"mfa_enabled": true
}
},
{
"name": "Bob Smith",
"id": "bob02",
"email": "bob@example.com",
"user_unique_id": "bob02",
"is_active": true,
"identities": [
"bob@example.com"
],
"groups": [
{
"id": "grp-engineering"
},
{
"id": "grp-admins"
}
],
"custom_properties": {
"department": "Engineering"
}
}
],
"groups": [
{
"name": "Engineering",
"id": "grp-engineering",
"group_unique_id": "grp-engineering",
"group_type": "Department",
"identities": [
"engineering@example.com"
],
"custom_properties": {
"is_security_group": false
}
},
{
"name": "Admins",
"id": "grp-admins",
"group_unique_id": "grp-admins",
"group_type": "Security",
"custom_properties": {
"is_security_group": true
}
},
{
"name": "Platform Team",
"id": "grp-platform",
"group_unique_id": "grp-platform",
"group_type": "Team",
"parent_group": {
"id": "grp-engineering"
}
}
]
}{
"custom_property_definition": {
"user_properties": {
"account_type": "STRING",
"account_status": "STRING",
"access_billable": "BOOLEAN",
"product_access": "STRING_LIST",
"user_type": "STRING"
},
"group_properties": {
"description": "STRING"
}
},
"name": "Atlassian Cloud Admin",
"principal_type": "Atlassian Cloud Admin",
"tenant": {
"name": "acme-corp",
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"tenant_unique_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
},
"users": [
{
"name": "Jane Doe",
"id": "5b10ac8d82e05b22cc7d4ef5",
"email": "jane.doe@acme-corp.com",
"user_unique_id": "5b10ac8d82e05b22cc7d4ef5",
"is_active": true,
"identities": [
"jane.doe@acme-corp.com"
],
"groups": [
{
"id": "jira-software-users"
},
{
"id": "confluence-users"
}
],
"custom_properties": {
"account_type": "atlassian",
"account_status": "active",
"access_billable": true,
"product_access": ["jira-software", "confluence"],
"user_type": "managed"
}
},
{
"name": "ext-contractor@partner.com",
"id": "7c20bd9e93f16c33dd8e5fg6",
"email": "ext-contractor@partner.com",
"user_unique_id": "7c20bd9e93f16c33dd8e5fg6",
"is_active": true,
"identities": [
"ext-contractor@partner.com"
],
"groups": [
{
"id": "jira-software-users"
}
],
"custom_properties": {
"account_type": "atlassian",
"account_status": "active",
"access_billable": true,
"product_access": ["jira-software"],
"user_type": "external"
}
}
],
"groups": [
{
"name": "jira-software-users",
"id": "jira-software-users",
"group_unique_id": "jira-software-users",
"group_type": "product-access",
"custom_properties": {
"description": "Users with access to Jira Software"
}
},
{
"name": "confluence-users",
"id": "confluence-users",
"group_unique_id": "confluence-users",
"group_type": "product-access",
"custom_properties": {
"description": "Users with access to Confluence"
}
},
{
"name": "org-admins",
"id": "org-admins",
"group_unique_id": "org-admins",
"group_type": "admin",
"custom_properties": {
"description": "Organization administrators"
}
}
]
}OAA Template for Human Resources Information Systems
Use this Open Authorization API template to publish employee metadata for Human Resources Information Systems (HRIS) platforms, typically used by organizations as a single source of truth for employee information.
Unlike an Identity Provider, HR platforms typically do not provide access to other systems. Employee profiles within an HRIS platform are instead used to store important details such as employment status, who individuals report to, department, and country. Veza can use this metadata to:
Trigger Lifecycle Management events when there is a change in the integrated HRIS data source.
Correlate employees in the HRIS system with identities in your identity provider (IdP).
Enrich Access Reviews with details about linked HRIS employees for users under review.
The template supports:
A top-level System entity representing the HRIS tenant, organization, or account.
Employee entities representing current and inactive workers
Group entities representing teams, departments, cost centers, or other units to which users are assigned.
To enable this payload format, specify the hris custom template when with the API.
The HRIS template supports . After specifying a custom property definition in the payload, you can assign additional attributes to entities. These enable attribute filters for searches and access reviews in Veza, and enrich results with entity metadata unique to the source system or your organization.
Veza maps HRIS employees to identities from integrated Identity Providers (IdPs) such as Okta by matching the idp_id, email, or employee_number value in the HRIS payload with the IdP entity's Name, Principal Name, or Identity. The matching process checks these fields in the following sequence:
idp_id
email
employee_number
If the idp_id is unset, Veza uses the email field for matching. If the email field is also absent, the employee_number is used. Veza issues a warning if no matching entity is found.
Veza compares only that one resolved value, and the comparison ignores case but is otherwise exact. An employee_number therefore correlates only when the IdP login, principal name, or email address is itself that number: Veza does not compare it to an Employee ID attribute on the IdP user. For the attributes Veza compares for each provider, see . To correlate on an attribute outside that set, add an identity_mapping_configuration to the HRIS system, or configure a mapping on the identity provider integration. See .
The account/tenant/etc. that contains the HR information.
Used to represent any person who has been employed by a company.
Used to represent any subset of employees, such as PayGroup or Team. Employees can be in multiple Groups.
{
"name": "HRIS Example",
"hris_type": "HR Platform",
"custom_property_definition": {
"system_properties": {},
"employee_properties": {
"job_level": "STRING"
},
"group_properties": {}
},
"system": {
"id": "7D8A21AE-6650-4357-842B-3FCEC8F29195",
"name": "HRIS Example",
"url": "https://hris.example.com",
},
"employees": [
{
"id": "123456",
"name": "jdoe",
"employee_number": "E123456",
"first_name": "John",
"last_name": "Doe",
"canonical_name": "Doe, John",
"email": "jdoe@example.com",
"home_location": "Anytown, CA",
"work_location": "San Francisco, CA",
"employment_status": "HIRED",
"start_date": "2022-05-22T00:00:00Z",
"job_title": "Software Developer",
"employment_types": [
"FULL_TIME"
],
"custom_properties": {
"job_level": "L3"
},
"is_active": true,
"groups": [
{
"id": "all_employees"
}
],
"managers": [
{
"id": "987654"
}
],
"department": {
"id": "engineering"
}
},
{
"id": "987654",
"name": "jane.doe",
"employee_number": "E987654",
"first_name": "Jane",
"last_name": "Doe",
"canonical_name": "Doe, Jane",
"email": "jane.doe@example.com",
"home_location": "Anytown, CA",
"work_location": "San Francisco, CA",
"employment_status": "HIRED",
"start_date": "2021-03-13T00:00:00Z",
"job_title": "Software Developer",
"employment_types": [
"FULL_TIME"
],
"custom_properties": {
"job_level": "M2"
},
"is_active": true,
"groups": [
{
"id": "all_employees"
}
],
"department": {
"id": "engineering"
}
}
],
"groups": [
{
"id": "all_employees",
"name": "All Employees",
"group_type": "Employee Group"
},
{
"id": "engineering",
"name": "Engineering",
"group_type": "Department"
}
]
}{
"name": "BambooHR",
"hris_type": "BambooHR",
"custom_property_definition": {
"employee_properties": {
"division": "STRING",
"office_extension": "STRING"
},
"group_properties": {
"headquarters_location": "STRING"
}
},
"system": {
"name": "BambooHR",
"id": "BambooHR",
"url": "https://vezai.bamboohr.com",
"idp_providers": ["okta"]
},
"employees": [
{
"name": "Charlotte Abbott",
"id": "1",
"custom_properties": {
"division": "North America",
"office_extension": "1234"
},
"employee_number": "1",
"email": "cabbott@efficientoffice.com",
"work_location": "Lindon, Utah",
"job_title": "Sr. HR Administrator"
},
{
"name": "Cheryl Barnet",
"id": "10",
"custom_properties": {
"division": "North America",
"office_extension": "5678"
},
"employee_number": "10",
"email": "cbarnet@efficientoffice.com",
"work_location": "Lindon, Utah",
"job_title": "VP of Customer Success"
}
],
"groups": [
{
"name": "North America-Human Resources",
"id": "North America-Human Resources",
"group_type": "Department",
"custom_properties": {
"headquarters_location": "Lindon, Utah"
}
}
]
}URL
url
String
Employee Number
employee_number
Group Type
group_type
String
N
N
The url for this HRIS system.
IDP Providers
idp_providers
String list
N
N
List of destination IdP provider types to connect this system to (e.g. okta, azure_ad).
Identity Mapping Configuration
identity_mapping_configuration
Object
N
N
Configuration for mapping employees to identities in external data sources.
String
N
Y
The employee's number that appears in the third-party integration.
Company
company
String
N
N
The company (or subsidiary) the employee works for.
First Name
first_name
String
N
N
The employee's first name.
Last Name
last_name
String
N
N
The employee's last name.
Preferred Name
preferred_name
String
N
N
The employee's preferred first name.
Display Full Name
display_full_name
String
N
N
The employee's full name, to use for display purposes. If a preferred first name is available, the full name will include the preferred first name.
Canonical Name
canonical_name
String
N
N
The employee's canonical name.
Username
username
String
N
N
The employee's username that appears in the integration UI.
email
String
N
Y
The employee's work email.
IDP ID
idp_id
String
N
N
The ID for this employee on the destination IDP provider used to automatically connect to it, if not supplied email is used.
Personal Email
personal_email
String
N
N
The employee's personal email.
Home Location
home_location
String
N
N
The employee's home location.
Work Location
work_location
String
N
N
The employee's work location.
Cost Center
cost_center
EntityRef
N
N
Reference to the group representing the cost center the employee is in (e.g. {"id": "cost-center-001"}).
Department
department
EntityRef
N
N
Reference to the group representing the department the employee is in (e.g. {"id": "engineering"}).
Managers
managers
EntityRef list
N
N
References to the employee's managers (e.g. [{"id": "987654"}]).
Groups
groups
EntityRef list
N
N
References to the groups this employee is in (e.g. [{"id": "all_employees"}]).
Employment Status
employment_status
String
N
N
The employment status of the employee. Possible values include - ACTIVE, PENDING, INACTIVE.
Is Active
is_active
Boolean
N
N
If the employee is active or not.
Start Date
start_date
Timestamp
N
N
The date that the employee started working. If an employee was rehired, the most recent start date will be returned.
Termination Date
termination_date
Timestamp
N
N
The employee's termination date.
Job Title
job_title
String
N
N
The title of the employee.
Employment Types
employment_types
String list
N
N
The employee's type of employment. Possible values include - FULL_TIME, PART_TIME, INTERN, CONTRACTOR, FREELANCE.
Primary Time Zone
primary_time_zone
String
N
N
The time zone which the employee primarily lives.
Y
N
The type of group, possible values include - TEAM, DEPARTMENT, COST_CENTER, BUSINESS_UNIT, GROUP. This is intended as to not have each type as their own nodes.
Parent
parent
EntityRef
N
N
Reference to the parent group (e.g. {"id": "parent-group-id"}).
Template for pushing custom data source entities and authorization
The Custom Application Template can be used to model most applications and services. It can describe many common entity types (such as users, groups, and resources), and should be the starting point for most custom connectors.
The template has three primary elements, covered in detail in this document:
Applications - describes one or more application instances for the custom data source. An application may consist of any of the following entities:
Local Users - defines the users of the application. The local user entity can be used to store the properties of the user specific to the application (such as last_login_at) and can be linked to a source identity such as Okta or Azure AD.
Local Groups - defines a group of users, permissions to the application or resources can be assigned to a group.
Local Roles - defines a collection of permissions. A role can be used to link an identity (local user, group, or IdP) to an application or resource. An identity assigned to a role will be assigned all permissions from that role.
Local Access Credentials - defines API keys, tokens, certificates, or other non-human authentication methods used by applications or services.
Resources - for more fine grain authorization tracking resources can be used to represent components of the application that have their own authorization. Users and groups can be assigned permission or roles to resources.
Sub Resources - resources can additionally have sub-resources for additional levels of depth.
Permissions - define the applications specific permissions and map to Veza canonical permissions.
Identity to Permissions - Assign local and federated users and groups to permissions or roles to the application and resources.
Additionally, a may describe user-configured key:pair values that can be applied to entities in the payload.
To use the generic app template, set the template type to application when creating a new data provider:
If your custom application exposes SCIM 2.0 compliant endpoints, you can enable automated provisioning and deprovisioning through Veza Lifecycle Management and Access Requests by setting the external_lifecycle_management_type parameter to SCIM:
This enables Veza to automate user provisioning, deprovisioning, and group membership management for your custom application. For detailed configuration and supported operations, see .
and can be applied to most objects in the OAA payload: the application and its local_users, local_groups, local_roles and resources/sub_resources.
Define custom properties
In the rest of the payload, for each object that should have additional properties, add a custom_properties array containing the property keys and values:
Use incremental updates to remove tags: Resubmitting a payload with different tags will apply any new tags, but not remove existing ones. To remove a tag already applied to an entity, you will need to use the
remove_tagoperation.
Validation and Troubleshooting
The API response will provide information for invalid data submission. You can check Veza events for updates on parsing status. Errors won't typically occur during parsing, as the metadata is validated upon push. To ensure a valid payload, you should:
Confirm all string fields are are valid UTF-8 strings no larger than 256 bytes.
Check that all required fields are present. Tags and properties are optional. You can null empty groups, roles, and other "empty" but required keys.
A 200 OK response may include warnings when matching IDP identities can't be found
The OAA payload must contain at least one top-level application. To model data systems with multiple components (such as different servers or repositories), applications can have resources and sub-resources.
You can also specify more than one application in the OAA payload, each with its own identities, permissions, roles, and resources.
The application_typeis applied to all application resources and identities, and can be used as a filterable property in Veza search.
Optional fields: some values in the schema are optional. When submitting a payload without a required field, an error message will help identify the issue. The following guidelines apply:
Any type of data in a JSON payload can be null (not set).
Unused optional arrays and objects should be empty {} or [].
Unused optional strings, numbers, and booleans should be null.
OAA apps need to contain at least one identity, which could be a local_group, local_role, or an IdP identity. Role assignments are made in the section.
Each application can contain one or more resources that users can access. Resources can have additional searchable properties and may contain additional sub-resources.
Sub-resources describe additional layers of the application principals can have authorization to, and support the same properties as resources, including additionally nested sub-resources.
An application can have any number of nested sub resources.
* A specific resource type must have only resources with an id, or only resources without an id. When used identity_to_permissions assignments are made by the id value and name functions as a display name.
In the system being modeled, application resources and sub-resources (such as virtual machines or Looker views) have access to other entities in the Veza Access Graph.
If an application resource or sub-resource is able to assume the permissions of a local user, IAM role, or Enterprise application, you can specify the connections to another graph entity node_type and id:
The following node types are currently available:
SnowflakeUser
GoogleCloudServiceAccount
AwsIamRole
Applications can have local users and groups for identities. For users and groups that correlate to an external Identity Provider (for example accounts automatically provisioned by the IdP), set the value that identifies them in that provider in identities. Veza compares each value against a fixed set of attributes per provider, listed in .
Contains any users whose profiles and authentication are handled and stored by the custom application. Local users include their group assignments and any federated identities that should be mapped to the local user:
If the application has any groups, describe each one in the local_groups array.
Group assignments for entities are defined in
identity_to_permissions.
*Each value must equal one of the attributes Veza compares on the identity provider. See .
Local roles define collections of local permissions that can be assigned to multiple resources. In the applications section, roles are named and mapped to permissions. Role assignments are defined in identity_to_permissions.
Access credentials represent API keys, tokens, certificates, or other non-human authentication methods used by applications or services.
permissions
Bind local permissions to the corresponding Veza canonical permission(s). Each native application permission should be included as an object, mapped to the corresponding data/non-data actions it allows.
Canonical permission types are:
DataRead
DataWrite
MetadataRead
To better model systems where roles can contain different permissions to different types of resources, permissions can apply to individual resource_types.
When the payload is parsed, individual permissions are created for each type of resource the permission applies to.
Without resource_types specified, the permission will function normally. When directly connecting principals and resources, resource_type is ignored.
Contains an object for each local and IdP identity, and the individual permissions to applications and resources.
You can bind permissions to federated users and groups by providing the principal’s IDP login email or group name as the identity, and setting the identity_type to idp.
Permissions and role assignments can apply to the entire application or scoped to specific resources.
For each identity (matching a local user, group, or IdP identity), state the identity type and add the assigned permissions/roles:
Each identity can be either a local_user, local_role, local_group, or local_access_creds name, or the identifier of an IdP user, group, or role (email address or group name).
identity_type must be one of: idp
application_permissions
Binds the identity (IdP entity, local user, or local group) to local permission, by application and resources.
role_assignments
Local roles are assigned to identities in the role_assignments array. Roles can apply to the entire application or only to specific (sub) resources.
The identity_to_permissions array defines how identities are authorized to applications and resources. Each entry maps an identity to its application permissions and/or role assignments. See the section above for field details.
Strings and string lists intended to have constant values (enums) such as identity_type may have a default value when not set.
AzureADEnterpriseApplication
TrinoUser
MetadataWrite
NonData
DataCreate
DataDelete
MetadataCreate
MetadataDelete
Uncategorized
local_userlocal_grouplocal_rolelocal_access_credscurl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
--compressed --data-binary '{"name":"DemoApp","custom_template":"application"}'curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{
"name": "MyCustomApp",
"custom_template": "application",
"external_lifecycle_management_type": "SCIM"
}' "custom_property_definition": {
"applications": [
{
"application_type": "sample",
"application_properties": {},
"local_user_properties": {
"license_type": "STRING",
"license_expires": "TIMESTAMP"
},
"local_group_properties": {},
"local_role_properties": {},
"role_assignment_properties": {},
"access_cred_properties": {},
"resources": []
}
]
} "local_users": [
{
"id": "001010",
"name": "bob",
"identities": [
"bob@example.com"
],
"groups": null,
"is_active": true,
"created_at": "2022-01-26T20:48:12.460Z",
"last_login_at": null,
"deactivated_at": null,
"password_last_changed_at": null,
"tags": [],
"custom_properties": {
"license_type": "pro",
"license_expires": "2023-01-01T00:00:00.000Z"
}
}
]{
"applications": [
{
"name": "Custom App",
"application_type": "Source Control",
"description": "Has a resource for each repository",
"custom_properties": {},
"tags": [],
"owners": [],
"local_users": [],
"local_groups": [],
"local_roles": [],
"resources": []
}
]
}name
string
Identifies the app in Veza Search. Used to bind permissions to the application
application_type
"resources": [
{
"name": "Entity1",
"id": "Unique ID",
"resource_type": "thing",
"description": "Some entity in the application",
"sub_resources": [
{
"name": "Child 1",
"resource_type": "child",
"description": "My information about resource",
"sub_resources": [],
"custom_properties": {},
"tags": [],
"owners": []
}
],
"custom_properties": {},
"tags": [],
"owners": []
},
{
"name": "Entity2",
"id": "Another Unique ID",
"resource_type": "thing",
"description": "Another entity in the application",
"sub_resources": [],
"custom_properties": {},
"tags": [],
"owners": [],
}
]name
string
Resource name. Primary ID for mapping users to individual resource permissions.
id
string
{
"name": "cog1",
"resource_type": "cog",
"connections": [
{
"id": "service_account@some-project.iam.gserviceaccount.com",
"node_type": "GoogleCloudServiceAccount"
}
]
}"local_users": [
{
"id": "egray",
"name": "Evan Gray",
"email": "egray@example.com",
"identities": ["egray@example.com"],
"groups": ["contractors"],
"is_active": true,
"created_at": "2020-12-19T16:39:57-08:00",
"last_login_at": "2021-11-19T14:19:30-08:00",
"password_last_changed_at": null,
"deactivated_at": null,
"custom_properties": {},
"tags": [],
"owners": []
}
]name
string
Name of the local user, shown in the Veza UI.
id
"local_groups": [
{
"name": "US Contractors",
"id": "us-contractors",
"identities": ["user1@company.com"],
"groups": [
"all-contractors",
"all-workers"
],
"tags": [],
"owners": []
}
]name
string
Name of the local group. Primary ID for mapping group to permissions.
id
string
"local_roles": [
{
"name": "administrator",
"id": "0001",
"permissions": ["create","destroy"]
},
{
"name": "operator",
"id": "0002",
"permissions": ["pull", "read"],
"tags": [],
"owners": []
}
]name
string
Name of the local role. Primary ID for mapping role to permissions.
id
string
"local_access_creds": [
{
"name": "Production API Key",
"id": "prod-key-001",
"created_at": "2023-01-15T08:00:00.000Z",
"expires_at": "2024-01-15T08:00:00.000Z",
"last_used_at": "2023-12-01T14:30:00.000Z",
"can_expire": true,
"is_active": true,
"custom_properties": {},
"tags": [],
"owners": []
}
]name
string
Name of the access credential
id
string
"permissions": [
{
"name": "Admin",
"permission_type": [
"DataRead",
"DataWrite",
"MetadataRead",
"MetadataWrite"
]
},
{
"name": "Operator",
"permission_type": [
"MetadataRead",
"DataRead"
]
},
{
"name": "Inactive",
"permission_type": [
"NonData"
]
}
]name
string
Native permission name, such as “Push” (used to bind local and IdP identities to native permissions).
permission_type
enum
"identity_to_permissions": [
{
"identity": "Evan Gray",
"identity_type": "local_user",
"application_permissions": [
{
"application": "Veza AI",
"resources": ["terraform-dev", "prod"],
"permission": "pull"
},
{
"application": "Veza AI",
"resources": ["terraform-dev", "prod"],
"permission": "push"
}
]
}
]identity
string
Principal name or email address. Maps to IdP login email or group name.
identity_type
string
{
"identity": "idpuser@org.co",
"identity_type": "idp",
"application_permissions":
[
{
"application": "source control",
"resources": ["util-tools", "terraform"],
"apply_to_application": false,
"permission": "write"
},
{
"application": "source control",
"resources": [],
"apply_to_application": true,
"permission": "read"
}
]
}application
string
Maps to an application name from the first section. Must exist in applications
resources
array
{
"identity": "john_smith",
"identity_type": "local_user",
"role_assignments":[
{
"application": "custom application",
"role": "administrator",
"apply_to_application": true,
"resources": []
},
{
"application": "custom application",
"role": "ops",
"apply_to_application": false,
"resources": ["oaa-vm-1"]
}
]
}application
string
The application where the role applies. Must exist in applications
role
string
"identity_to_permissions": [
{
"identity": "0000000001",
"identity_type": "local_user",
"role_assignments": [
{
"application": "Sample App",
"role": "user",
"apply_to_application": true,
"resources": []
}
]
},
{
"identity": "0000000002",
"identity_type": "local_user",
"role_assignments": [
{
"application": "Sample App",
"role": "user",
"apply_to_application": true,
"resources": []
},
{
"application": "Sample App",
"role": "admin",
"apply_to_application": true,
"resources": []
}
]
}
]
string
Applied to all entities within the application as a searchable property. Multiple instances of an application can share the same type
description
string
Any additional notes to show in the entity details, limit 256 characters
custom_properties
dictionary
contain property_values validated against the custom_property_definition
tags
array
Specify tags with a key and optional value (optional)
owners
array
See
local_users
array
Contains zero or more local users (see ).
local_groups
array
Contains zero or more (collections of users).
local_roles
array
Defines permissions for any within the application.
local_access_creds
array
Contains any for the application.
local_agents
array
Contains any AI agent entities for the application.
local_models
array
Contains any AI model entities for the application.
resources
array
Contains any and sub-resources.
okta_app_id
string
(Optional, early access) The Okta Application ID for this application. When set, Veza enriches local users with sso_last_login_at timestamps from Okta SSO activity. Requires Veza Support to enable Okta SSO last login enrichment for your tenant. See .
Optional value to use as the unique ID, instead of the resource name*.
resource_type
string
Searchable label for the resource type. The application entity details in Veza will show the contained resource types as properties.
description
string
Shown in Veza entity details, max 255 characters.
custom_properties
dictionary
See .
sub_resources
array
Used for additional resource layers, nested data sources, services, and so on.
connections
Optional list of resource connections to external entities discovered by Veza
tags
array
Specify tags with a key and optional value (optional)
owners
array
See
string
Optional identifier to use for mapping users to groups, roles, and permissions.
email
string
User email address (optional). Separate from identities, this is a display/metadata field on the user entity.
identities
identities array
Correlates the user to a federated identity. Use when your IdP provisions local accounts, or if the local user can be assumed by an external group. Each value must equal one of the attributes Veza compares on the identity provider, such as an Okta login or an Entra ID principal name. See .
groups
groups array
List of any memberships as strings. Must exist in local groups.
access_creds
array
List of local_access_creds IDs associated with this user (optional).
is_active
boolean
If activity state is available from the provider, use this field to make the value available as a searchable property (optional).
user_type
string
Distinguishes between human and service_account user types (optional). Useful for identifying non-human accounts in access reviews.
principal_id
string
The ID for this user in a linked principal template, used for automatic connection. If not supplied, the user id is used (optional).
created_at
RFC3339 string
User creation date (optional), for example 1996-12-19T16:39:57-08:00.
last_login_at
RFC3339 string
(optional)
password_last_changed_at
RFC3339 string
(optional)
deactivated_at
RFC3339 string
(optional)
access_creds
array
List of access credential id values associated with this user (optional). Links the user to their API keys, tokens, or other credentials defined in local_access_creds.
custom_properties
dictionary
See .
tags
array
Specify tags with a key and optional value (optional).
owners
array
See
Optional identifier to use for permissions mapping.
identities
array
If IdP users are members of the local group, or if the local group directly maps to an IdP group, list them here.*
groups
array
List of local groups this group is a member of (for applications that support adding groups to other groups).
access_creds
array
List of local_access_creds IDs associated with this group (optional).
created_at
RFC3339 string
Group creation date (optional).
custom_properties
dictionary
See .
tags
array
Specify tags with a key and optional value (optional).
owners
array
See .
Optional identifier to use for permissions mapping.
permissions
array
Permissions associated with the role. Must exist in permissions.
roles
array
List of sub-role names for nested role hierarchies (optional). An identity assigned to this role inherits all permissions from its sub-roles.
custom_properties
dictionary
See .
tags
array
Specify tags with a key and optional value (optional).
owners
array
See .
Unique identifier for the credential
created_at
RFC3339 string
When the credential was created (optional)
expires_at
RFC3339 string
When the credential expires (optional)
last_used_at
RFC3339 string
Last time the credential was used (optional)
can_expire
boolean
Whether the credential can expire
is_active
boolean
Whether the credential is currently active
custom_properties
dictionary
See
tags
array
See
owners
array
See
List of canonical privilege(s) the permission represents.
apply_to_sub_resources
bool
To more accurately model applications where permissions should apply to any children of a resource, set TRUE to define the permission as inheritable. This eliminates the need to include the permission at each sub level.
resource_types
array
Optional list of resource type strings. When specified, separate permission nodes are created per resource type. See below.
Sets whether the identity corresponds to an IdP identity, or is local to the application
application_permissions
array
List each local permission available to the identity (must be a valid permission name from the previous section).
role_assignments
array
Any roles assigned to the identity, and the resources they apply to (role/resource must exist in applications).
List of application resource or sub-resource names to apply the permission. Must exist in applications
apply_to_application
boolean
Set to true to model environments where permissions apply to the top-level application as well as its resources.
permission
string
Maps to a permission name from the second section. Must exist in permissions
The role name. Must exist in local_roles
apply_to_application
boolean
Set to true to model environments where the role applies to the top-level application and all its resources.
resources
array
List of resources and sub-resources where the role applies. Must exist in applications
assignment_properties
dictionary
Custom properties on the role assignment itself (optional). Must be defined in role_assignment_properties within custom_property_definition. Useful for tracking assignment-specific metadata such as assignment date or expiration.
{
"custom_property_definition": {
"applications": [
{
"application_type": "sample",
"application_properties": {},
"local_user_properties": {},
"local_group_properties": {},
"local_role_properties": {},
"resources": []
}
]
},
"applications": [
{
"name": "Sample App",
"application_type": "sample",
"description": "This is a sample app",
"local_users": [
{
"id": "0000000001",
"name": "bob",
"identities": [
"bob@example.com"
],
"is_active": true,
"created_at": "2022-01-26T20:48:12.460Z"
},
{
"id": "0000000002",
"name": "jane",
"identities": [
"jane@example.com"
],
"groups": [
"admins"
],
"created_at": "2021-08-13T06:28:13.250Z"
}
],
"local_groups": [
{
"id": "admins",
"name": "Administrators"
}
],
"local_roles": [],
"tags": [],
"custom_properties": {},
"resources": [
{
"id": "0001",
"name": "Entity1",
"resource_type": "thing",
"description": "Some entity in the application",
"sub_resources": [
{
"name": "Child 1",
"resource_type": "child",
"description": "My information about resource"
}
]
},
{
"id": "0002",
"name": "Entity2",
"resource_type": "thing",
"description": "Another entity in the application"
}
]
}
],
"permissions": [
{
"name": "admin",
"permission_type": [
"DataRead",
"DataWrite"
],
"apply_to_sub_resources": false,
"resource_types": []
},
{
"name": "operator",
"permission_type": [
"DataRead",
"MetadataRead"
],
"apply_to_sub_resources": false,
"resource_types": []
},
{
"name": "manager",
"permission_type": [
"MetadataWrite"
],
"apply_to_sub_resources": false,
"resource_types": []
}
],
"identity_to_permissions": [
{
"identity": "0000000001",
"identity_type": "local_user",
"application_permissions": [
{
"application": "Sample App",
"permission": "operator",
"apply_to_application": true
},
{
"application": "Sample App",
"resources": [
"0001"
],
"permission": "manager"
}
]
},
{
"identity": "admins",
"identity_type": "local_group",
"application_permissions": [
{
"application": "Sample App",
"permission": "admin",
"apply_to_application": true
}
]
}
]
}{
"applications": [
{
"name": "Sample App",
"application_type": "sample",
"description": "This is a sample app",
"local_users": [
{
"name": "bob",
"identities": [
"bob@example.com"
],
"is_active": true,
"created_at": "2022-01-26T20:48:12.460Z",
"id": "0000000001"
},
{
"name": "jane",
"identities": [
"jane@example.com"
],
"created_at": "2021-08-13T06:28:13.250Z",
"id": "0000000002"
}
],
"local_groups": [],
"local_roles": [
{
"id": "admin",
"name": "Administrator",
"permissions": [
"manage_users"
],
"tags": [],
"custom_properties": {}
},
{
"id": "user",
"name": "User",
"permissions": [
"view_tickets",
"close_tickets"
],
"tags": [],
"custom_properties": {}
}
],
"tags": [],
"custom_properties": {},
"resources": []
}
],
"permissions": [
{
"name": "manage_users",
"permission_type": [
"MetadataWrite"
],
"apply_to_sub_resources": false,
"resource_types": []
},
{
"name": "view_tickets",
"permission_type": [
"DataRead"
],
"apply_to_sub_resources": false,
"resource_types": []
},
{
"name": "close_tickets",
"permission_type": [
"MetadataWrite"
],
"apply_to_sub_resources": false,
"resource_types": []
}
],
"identity_to_permissions": [
{
"identity": "0000000001",
"identity_type": "local_user",
"role_assignments": [
{
"application": "Sample App",
"role": "user",
"apply_to_application": true,
"resources": []
}
]
},
{
"identity": "0000000002",
"identity_type": "local_user",
"role_assignments": [
{
"application": "Sample App",
"role": "user",
"apply_to_application": true,
"resources": []
},
{
"application": "Sample App",
"role": "admin",
"apply_to_application": true,
"resources": []
}
]
}
]
}