Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Graph search concepts for working with the query builder
An entity, also referred to as a node, represents an authorization, data, or identity object discovered by Veza. It can be a concrete external named entity, such as AwsIamPolicy or OktaUser, or an edge aggregation node created by Veza for visualization and service purposes.
Entities, within the context of the Query Builder API, are the building blocks that represent various authorization, data, and identity objects discovered by Veza. They are used to construct queries, workflows, and Authorization Graph searches.
Entities encompass a wide range of elements, including identities, local users, data resources, identity domains, and IAM or RBAC elements such as security groups, policies, and roles.
When constructing queries, you will typically specify the source and destination entity types, such as Okta User to AWS S3 Bucket or Google User to Google Group, along with specific constraints on those entity types.
The Query Builder API offers top-level Entity Type Groupings such as User and Resource, providing an easy way to select and constrain all entities belonging to a particular supertype.
An entity attribute is a key-value pair associated with a specific entity type. These attributes carry rich metadata, enabling granular filters and search conditions.
Veza will add certain properties such as name, is human, or full admin during parsing. Other attributes such as mfa_enabled and is_encrypted can be directly ingested from the provider.
An entity type represents the final and precise specification of a node's category in an external system. Examples of external entity types include AwsIamUser, or S3Bucket.
An entity type grouping, or supertype, provides a top-level label to search for multiple entity types in a single query, such as User or Resource. Constraints can apply to an entity type grouping as if it were a single entity.
Supertypes are groupings of entities in the graph, allowing the specification of a "one of" style constraint among different concrete node types. A node type can be a member of one or more supertypes, and a supertype can contain concrete node types as well as other supertypes.
Raw or System permissions refer to individual privileges defined in the provider's internal terms, for example, AWS IAM s3:BucketDelete.
Effective Permissions represent the canonical C/R/U/D equivalents of system permissions. For example, MetadataWrite, DataRead, NonData.
Note: When filtering by permission, you must specify the type of permission. Effective and system permissions cannot both be specified for the same query. If a search does not involve privileged relationships to resources, the permissions filter has no effect (e.g., User->Policy search).
Veza supports two types of tags:
Veza Tags: These are key or key-value pairs that users add to Authorization Graph entities.
Provider-Specific Tags: Veza also discovers tags specific to providers, such as AWS tags and Google Cloud labels.
API overview and sample queries
As Veza does not write changes to your environment, you can use the query builder API to build your own tools and integrate Veza with your internal systems and security processes.
For example, you might use Veza APIs to:
Programmatically detect and add Snowflake users to a role when another role already exists with the required permissions
Progressively query for data resources matching a naming pattern or other condition, and apply tags with the provider's built-in APIs
Discover and alter overly permissive policies granting access to sensitive data
Your Veza success team can offer additional support and access to development tools including a Python SDK. This guide covers some simple examples to help get started with custom queries, including links to additional documentation.
Sample Request
See Query Builder Parameters for more information about possible options.
Sample Response
The response always returns a value, next_page_token, and has_more. If more results are available, you can get the next page of results by passing the page_token in the request query.
The values array will contain the Individual entity details:
id
Unique Authorization Graph entity ID.
type
Type of entity.
destination_node_count
Number of related entities matching the query conditions.
permissions
For more information, see Query Builder Results.
Sample Request
Sample response
Use the query ID to run a saved query. Just as for query_spec operations, you can request the paginated entity details or the result count, or get destination nodes for a result:
Responses will contain the node details or the total count, depending on the method used.
The is fundamental to and , enabling external notifications and enhanced search visibility based on query constraints and conditions. When combined with for remediation workflows, these can offer in-the-box tools to begin integrating Veza with external processes.
To run the provided commands, you'll need to first generate a token from Administration > . You'll also need to know the base URL of your Veza deployment, such as your-org.veza.com.
You can validate that a query is functioning as intended before saving it with , which will return the total number of entities in the search results.
returns a paginated list of query results, including entity details. This operation does not return a total count of results. A query spec does not require the full saved query , and instead takes a condensed payload.
returns the related destination nodes for a single entity in the results of a saved query. This endpoint can be used, for example, to review the related roles for an individual user when the query specifies User > Role.
Post your request to or , depending on whether you need a list of the included nodes (including all entity properties), or want the full result count:
For , the permissions the source entity has to a specific destination entity.
Use to find the related entities for an individual result for a query spec. Specify the source_node_id of the entity to get relationships for:
If you want to run the same query repeatedly, or enable Veza or based on the results, you can save it under .
A saved query includes a name and description, along with any other .
Sample Request:
Sample response:
A successful response returns the saved query id, and full query specification in a value object:
CreateAssessmentQuery saves a new query with the specified conditions. See for all available constraints and options. To run a query without saving it, see the query spec operations.
To return results, the query must specify a related entity type and cannot use the no_relation option.
Sample request:
Sample response:
GetAssessmentQueryDestinationNodes returns details about related destination nodes for an individual result, specified by source_node_id. returns source nodes.
ListAssessmentQueries retrieves a list of all built-in and user-created queries.
By default, this endpoint returns only the queries that are currently enabled. When the risks_only parameter is set to true, it will only return queries with a risk level.
Sample request
Sample response:
See for more information about the saved query object.
Examples and descriptions for query builder responses
Depending on the request, query results can be returned as a collection of entities (nodes), a numeric value, or a timestamp.
result_type
string
Indicates whether the query returns nodes details, node count, or timestamp.
nodes_value
array
Contains node details (see below)
number_value
string
The count of nodes in the query results.
timestamp_value
string
Not currently supported
result_node_type
string
The type of nodes returned in the search results.
next_page_token
string
Pagination token
has_more
boolean
Indicates if more results are available
Node details
The node values contain individual entity details, including any properties Veza has discovered such as manager or date_created:
id
string
The node's UUID in the Veza data catalog
type
string
The node type.
properties
dict
List of any entity properties, as key:value pairs
destination_node_count
int
For DESTINATION_NODES queries, the number of connected nodes.
permissions
array
The permissions a source node has to the destination resource.
GetAssessmentQuery retrieves a single saved query object based on the query ID.
Sample request:
Creating new queries, interacting with saved queries, and running query specs
Queries created with these endpoints can define risks and have rules and alerts associated with them. Even if you and your team create and manage queries primarily from the user interface, this documentation may still be of interest for learning how queries are constructed and handled within Veza.
You can use these methods to:
These endpoints are available under {{VezaURL}}/api/v1/. You must use the appropriate prefix when calling the API, for example:
Requesting a query will return the result value, which can be a total number of results, the node details, or a timestamp. To return a paginated list of node details instead, use .
The Query Builder APIs enable programmatic creation, execution, and management of assessment queries, using the Veza the . You can use these operations to develop your own tools and integrate Veza search with external services and automation.
For more information about query options, see .
You can create and manage for your user account from Administration > API Keys. Each API call must include the API key in the request header, passed as a bearer authentication token.
The page consolidates some sample requests and responses.
An understanding of Veza's usage of may be helpful. To learn more about the query object and options, see . For more information about how to interpret the query response body, see .
You can start working with pre-built and saved queries using the /assessments/queries endpoint. When you are ready to try running your own queries, see the operations to run test queries without saving them.
UpdateAssessmentQuery updates an existing saved query by id, with the provided full body. Partial updates are not currently supported.
Sample request:
{id} (path) - string - ID of the query to modify.
Sample response:
A successful response will include the query details within a value object:
DeleteAssessmentQuery removes a query by ID.
By default, this operation does not delete assessments that are currently included in a report. Set the force option to true to delete an assessment regardless of its usage in reports.
Sample request:
Sample response:
A successful response will be empty:
Options for saved and spec query requests
Queries begin with a source node type and optionally a destination node type. A simple query might show "all Okta users with relationships to S3 Buckets". A more advanced query will add additional constraints on entity attributes or tags, or filter on relationships to intermediate entities, such as a role, group, or local user.
A collection of node specifications, defining constraints or other query parameters on each entity type.
You can query for a single principal or resource by filtering on node ID.
Contains the type, tags, and conditions applied to a node, narrowing the focus of the query.
Note that you can add conditions and tags to either the source node type or the destination.
Query specs support supertypes with constraints. They can specified in the same way as concrete node types. node_type_grouping_constraint can be used to limit the concrete node type set belonging to the specified super type, with possible constraint type values EXCLUDE or INCLUDE. Example spec:
Additional constraints can be applied using a node condition_expression. Conditions specified within the expression can target node attributes such as name, date created, or any other properties Veza has discovered.
Conditions can always apply to source and destination node types. Conditions can only apply to intermediate node types when the query defines required_intermediate_node_types.
Conditions have a function (fn). Valid operators are:
EQ: 'Equals',
LT: 'Less Than',
LTE: 'Less Than or Equal',
GT: 'Greater Than',
GTE: 'Greater Than or Equal',
LIST_CONTAINS: 'List Contains',
IN: 'In',
STARTS_WITH: 'Starts With',
CONTAINS: 'Contains',
ENDS_WITH: 'Ends With',
EXISTS: 'Exists',
REGEX: 'Matches Regular Expression',
Date-based operators can be:
LT: 'Not in the Last', LTE: 'Before', GT: 'In the Last', GTE: 'After', EQ: 'At',
For example:
The condition value can be true, false, a number, an RFC3339 timestamp, or a string. For example, to find S3 Bucket destinations where public ACLs haven't been blocked:
Conditions can also contain a string-typed value. For example, to find all Okta users with the prefix "sa-":
Note that you can specify nodes where the condition doesn't apply by setting "not": true for the constraint.
There can also be a not on the whole expression:
You can get all the properties available for different node types (which vary depending on the provider and service) by searching for the entities in Authorization Graph and viewing the node details.
When applied to source or destination node types, results will only show entities with (or without) a specific Veza Tag or a discovered AWS tag. For example:
tags and excluded_tags can always apply to source and destination node types. They can only apply to intermediate node types in assessment queries, when the spec defines required_intermediate_node_types.
Enable no_relation to only return nodes without a relationship to the destination node types. For example, to show Microsoft Azure AD users that do not belong to the group "Alabama":
You may want to query for entities that have direct access to a resource, without a specific intermediate relationship. For example, you can query for IAM users whose resource access does not also involve a role.
To query for relationships that do not include a specific node type in the authorization path, specify an exclusion in the avoids_intermediate_node_types object:
To return only entities with one or more permissions to a resource, you can list either system or effective permissions, with an AND or OR operator.
"Raw" or "System" permissions describe privileges using the service providers terms, for example s3:PutBucketAcl.
You can review all the possible permissions Veza has discovered for an entity by selecting it as a related entity in a Query Builder search. The "Permissions" dropdown menu will include all effective and raw permissions for the resource type.
Effective permissions are an abstraction of an entity's authorization to a resource. When discovering authorization metadata for a connected provider, Veza maps each raw permission a principal has on a resource to the corresponding canonical permission, and calculates the cumulative effective permissions.
Queries constructed using the v1 API and the Segregation of Duty page can use "relates to" expressions to get results based on relationships to more than one related entity types, with AND | OR logic. For example: Show all users that are in Group A and Group B, or Show users that are in Group X and have Role Y.
For E = { specs: [A, B, ...], child_expressions: [X, Y, ...], operator, not }
"source has a path to E" is defined as:
If operator is AND (default): "source has a path to ALL of (A,B, ..., X, Y, ...)"
If operator is OR: "source has a path to ANY of (A,B, ..., X, Y, ...)"
If not = true, boolean invert the result above
and_op_type: AndOperatorType (INFERRED [default], SOURCE_INTERSECT, PAIR_INTERSECT)
child_expressions: RelatesToExpressions Array
not: Boolean flag applied to specs and child_expressions
operator: Operator (AND [default], OR)
specs: RelatesToSpec array specifying node types and conditions
INFERRED (default): Replaced with SOURCE_INTERSECT or PAIR_INTERSECT based on query execution context.
SOURCE_INTERSECT: Intersection based on source node.
PAIR_INTERSECT: Intersection based on pairs of nodes.
Given the following graph relationship:
U1 and U2 are entity type U, and R1 and R2 are entity type R. Here U2 is in the result of U-> (P1->R AND P2->R) with SOURCE_INTERSECT. With PAIR_INTERSECT, U2 is not in the result because neither R1 or R2 matches both U->P1->R and U->P2->R.
If we change the graph to have R1 match both U->P1->R and U->P2->R:
Now U2 is in the result of the same query with PAIR_INTERSECT. PAIR_INTERSECT makes more sense for queries like “users have permission A && B to database” when the meaning is “permission A && B to the same database”
AndOperatorType defaults:
INFERRED will be replaced with one of SOURCE_INTERSECT or PAIR_INTERSECT when executing the query.
INFERRED is replaced with PAIR_INTERSECT only if:
The query doesn't have RelatesToExpression.Not == true in any child expressions, and
All operands of the AND have the same sole node type, and
All operands of the AND don't include conflicting "equal to" conditions on unique property (id and name)
Otherwise INFERRED is replaced with SOURCE_INTERSECT
A RelatesToSpec represents a precise path definition:
source has a path to any node spec in node_types
direction determines the direction of the path
the path has all required_intermediate_node_types
the path has none of avoided_intermediate_node_types
all or any of raw_permissions appear on the path, depending on raw_permissions.operator
all or any of effective_permissions appear on the path, effective_permissions on raw_permissions.operator
if no_relation=true, it instead means such a path does not exist
RelatesToDirection can be:
ANY_DIRECTION : Direction to be chosen by the API. Paths of any direction is accepted by the caller.
SINGLE_DIRECTIONAL: Direction to be chosen by the API if there is only one valid direction. Otherwise this input is invalid.
OUTGOING: Only accept result for paths of ( -> ...). This input is invalid if there is no such a path in schema.
INCOMING: Only accept result for paths of (... -> ). This input is invalid if there is no such a path in schema.
See and for more details on the saved query object.
When calling endpoints or , you will specify the search parameters in a JSON object in the request body. Saved queries and query specifications support a range of parameters and options, described in this document.
Most requests will return entities of the source node type. Use or to return related entities for an individual source entity in a query result.
As the Veza uses these APIs, you can preview different sample requests and responses by constructing queries from the web interface, opening the Save dropdown menu, and choosing View Query Spec API.
define conditions on entity types to mark exceptions for queries with a risk level.
nodes
node spec array
Contains an object for each node type
nodes_operator
string
Sets whether all or any of the node conditions must be true (AND(default), OR).
SYSTEM_CREATED
Used for pre-built system queries.
SOURCE_TO_DESTINATION
The search will return entities of the source node type with a relationship to the destination entity type.
DESTINATION_NODES
Return the destination nodes, instead of source nodes (deprecated, use query_spec:destination_nodes).
values
string
String list of raw permission names
operator
string
AND, OR (default AND)
values
string
Effective permissions can be METADATA_WRITE, METADATA_READ, METADATA_CREATE, METADATA_DELETE, DATA_READ, DATA_WRITE, DATA_CREATE, DATA_DELETE, NON_DATA ] (default METADATA_WRITE)
operator
string
AND, OR (default AND)
all_entity_condition
A constraint to apply on all entities that happen to be a part of the query result (specified or not)
analysis_type
string
For built-in queries, indicates where the query originated (Query Builder or the Analysis page). Values can be UNSET USER GROUP ROLE or SEPARATION_OF_DUTY
avoided_intermediate_node_types
Any entity types that cannot exist in the path between the query source and destination.
description
string
A description of the assessment query, shown in the query details.
destination_node_types
If specified, results only include entities with a relationship to the destination node type.
effective_permissions
Effective permissions to search, and operator to use.
labels
array of strings
List of assessment labels for categorization in reports.
name
string
The name of the assessment query, shown in the Veza UI.
no_relation
boolean
deprecated (use relates_to_exp)
node_relationship_type
string
Query mode EFFECTIVE_ACCESS (default) or CONFIGURED.
query_type
string
always use SOURCE_TO_DESTINATION
raw_permissions
If specified, only return results that have the listed raw permissions.
relates_to_exp
Specify related note constraints
required_intermediate_node_types
Specifies requirements for the path connecting the source and destination nodes.
risk_level
string
Sets whether results are marked as risks based on the risk level: NONE (default), WARNING, or CRITICAL
risk_suppressed_constraints
Adds a risk exception for nodes matching the specification.
source_node_types
The source node type to return as results for SOURCE_TO_DESTINATION queries (for example AwsIamUser). Required to have only 1.
violation
boolean
Deprecated, use risk_level instead
visibility
string
Sets whether a query is public or visible only to owners. PUBLIC (default) or PRIVATE
include_nodes
boolean
When true, only return a result count.
condition_expression
Logical tree of constraints to apply
conditions
array
Deprecated, use condition_expression
count_conditions
array
Count condition functions and values. count_conditions are only accepted in assessment queries, when the node spec defines destination_node_types.
direct_relationship_only
boolean
When set to true, self-referential edges on this node type will not be traversed. For example, if the node type is Role and direct_relationship_only is true, then any edge Role -> Role will be ignored. Can only be used with destination or source node types with self-referential edges. Cannot be used with labels.
excluded_tags
tags to exclude from results.
node_id
string
For specifying an individual entity, a single graph entity ID
node_type
string
Concrete node type (e.g. AwsIamUser) or node label (e.g. User)
node_type_grouping_constraint
Contains an operator and list of node types to include or exclude
tags
tags to require, specified with key value pairs.
avoided_intermediate_node_types
direction
string
RelatesToDirection
effective_permissions
no_relation
boolean
node_types
raw_permissions
object
A collection of raw permission names
required_intermediate_node_types
GetAssessmentQueryNodes returns node details for entities in the query results, with a paginated response.
Sample request:
Sample response:
GetAssessmentQueryResult returns the total number of results for a saved query.
Sample request:
Sample Response:
The response will include a number_value representing the total number of results.
Documentation for Veza's private APIs for advanced access assessments
This section contains documentation for APIs in the private/ namespace for advanced access assessment capabilities. These APIs currently support advanced role analysis, entitlement comparisons, and access management for Snowflake environments.
Identifies grantees (such as roles) that provide specific access permissions to a given identity for a set of resources
Checks whether a role with specific resource permissions already exists
Simulates modifications to an existing role's permissions and checks if other roles with the resulting permission set already exist
Provides insights into role accessibility for users within a specified cost center
These APIs enable several identity security use cases:
Role Rationalization: Identify and consolidate redundant roles to simplify access management
Least Privilege Implementation: Find roles that provide necessary access with minimal excess permissions
Access Governance: Maintain a minimal set of roles by identifying functionally equivalent roles
Access Pattern Analysis: Discover common access patterns among users in the same organizational unit
Privileged Access Management: Analyze what additional privileges different roles would provide to a user
Some APIs may have performance limitations with highly connected identities or complex permission structures.
GetAssessmentQuerySpecResult Returns the total count of results for a query specification.
The response will include a number_value representing the total number of results.
Sample request:
Sample response:
The response will contain a number_value of total results:
GetAssessmentQuerySpecNodes returns the entity details for nodes in the query without generating a result count. This option uses pagination and can be faster for complex queries where the total number of search results is not needed.
The request must include the full query spec object and the source_node_id of the query result to retrieve destination nodes for. Additionally, providing a snapshot_id will return destination nodes based on a Time Machine snapshot.
When specifying a page_size in the query string, responses will include the next_page_token and indicate has_more if additional results are available. Note that a page can be empty even when more results exist.
Sample request:
The following example searches for AWS IAM users with permissions to modify S3 bucket ACLs:
Sample response:
Here is a more complex example, which identifies Okta Users related to Snowflake Local Roles.
Using conditions, the query will only return users related to the BILLING group AND another group, either the AUDITOR role OR ROLE_A
Request:
Response:
GetAssessmentQuerySpecDestinationNodes returns the related destination nodes, including effective permissions, for a single entity in the results of a saved query.
Sample request:
The request must include the full query spec object, and the source_node_id of the query result to return destination nodes for. You can additionally provide a snapshot_id to query against historical data.
Sample response:
object
object
object
object
array
object
array
object
object
object
object
Please note that the total number of the results is not provided . To get a result count, use .
To get node details for the source entity type, use . To get related destination nodes for an individual result, use .
These features are currently limited to the .
Create, apply, and remove Veza tags
For the examples below, BASEURL should be the address of your Veza instance, such as https://<org>.vezacloud.com.
Use Get Query Spec Nodes to find Snowflake tables reachable by federated Okta users belonging to the Finance department:
The response will include the table id:
Apply a tag by specifying a key and optional value:
Remove a tag by providing the entity id and the tag key to delete:
Check whether a role with specific resource permissions already exists.
Early Access: This API is provided in Early Access. Please contact our customer support team for more information and to enable this feature.
The Role Existence API allows users to check whether a role with specific resource permissions already exists in the system. This API is particularly useful for role management and access governance in Snowflake environments.
This API enables efficient role management by identifying existing roles that already have the permissions you're looking for. Key use cases include:
Role Discovery: Find existing roles that match specific permission requirements
Prevent Role Proliferation: Avoid creating duplicate roles with the same permissions
Permission Auditing: Verify which roles have specific permissions to resources
Role Standardization: Identify standard roles that can be reused for similar access requirements
The API accepts a request object with the following parameters:
Each ResourcePermissions object contains:
The API uses the following protocol buffer message definitions:
The API returns a response object with the following field:
This example checks if there's an existing role with USAGE permission on a specific Snowflake database:
The response indicates that a matching role exists:
You can check for roles that have permissions across multiple resources:
In this example, the request is checking for roles with specific permissions, but no matching roles are found:
The response indicates that no matching roles with the specified permission combination exist:
When you receive an empty response like this, it suggests that a new role might need to be created to satisfy these specific permission requirements, as no existing role has the exact permission set requested.
Modify role permissions and find matching existing roles.
Early Access: This API is provided in Early Access. Please contact our customer support team for more information and to enable this feature.
The Role Maintenance API allows you to simulate modifications to an existing role's permissions and check if other roles with the resulting permission set already exist. This API is particularly useful for role rationalization and consolidation in Snowflake environments.
This API enables effective role maintenance and governance with several key capabilities:
Role Rationalization: Find existing roles that match a desired permission set after modifications
Role Consolidation: Identify opportunities to consolidate roles by checking for existing roles with similar permissions
Permission Planning: Plan permission changes and identify existing alternatives before implementation
Access Governance: Maintain a minimal set of roles by identifying functionally equivalent roles
The API accepts a request object with the following parameters:
Each GranteeModification object contains:
Note: You can specify either or both of these fields:
If only from_resource_permissions is set, those permissions will be removed
If only to_resource_permissions is set, those permissions will be added
If both are set, the permissions will be updated accordingly
This flexibility allows you to model different types of permission changes within a single API call. For example, you can simultaneously remove access to one resource while adding access to another, or modify permission levels on the same resource.
Each ResourcePermissions object contains:
The API uses the following protocol buffer message definitions:
The API returns a response object with the following field:
This example simulates removing database and schema permissions from one role while adding database permissions to another:
The response indicates that a role with the resulting permission set exists:
This example shows adding permissions to a role:
This example shows removing permissions from a role:
Create, apply, and remove Veza tags
New in 2022.3.2: Tagging operations are now available as part of the
v1/API set.
Post {VezaURL}/api/v1/graph/tags
Define a new tag that can be applied to any discovered entity, as a key:value pair. The tag value is optional.
A successful response will be empty ({}).
Post {VezaURL}/api/v1/graph/nodes/tags
Apply one or more tags to an entity by providing an entity ID. A new Tag will be created if one doesn't already exist.
To retrieve an entity ID, you can use the Query Builder API, or browse the Identity Data Entities catalog.
Post {VezaURL}/api/v1/graph/nodes/tags:remove
Remove a tag from an entity.
A successful response will be empty ({}).
Identify grantees (such as roles) providing specific access permissions to a given identity for a set of resources.
Early Access: This API is provided in Early Access. Please contact our customer support team for more information and to enable this feature.
The GetAccessRelationship API takes an identity (user), a list of resources with permissions, and responds with potential grantees (roles) that can grant these access permissions to the user. The response includes detailed information about the additional access these grantees would provide. This API is particularly designed for role recommendations and permissions analysis in Snowflake environments.
This API returns potential grantees (i.e., Snowflake roles) that can provide specific permissions, with results ordered by the level of "extra access" they provide (access not already available to the user). The response includes comparisons between current access and potential access and supports filtering by grantee type and other criteria.
Role Recommendations: Find the most appropriate roles to grant a user for specific access needs
Privilege Analysis: Analyze what additional privileges different roles would provide to a user
Access Management: Compare different access options before making permission changes
Least Privilege Implementation: Identify roles that provide necessary access with minimal excess permissions
For highly connected identities (>10,000 accesses or accessible resources), the calculation of "extra access" can be performance-intensive. For a timely response, the API will return grantees with the least resources by themselves, instead of those providing the least extra resources. In such cases, is_identity_highly_connected will be set to true in response.
The API accepts a GetAccessRelationshipRequest object with the following parameters:
Important: Either
resource_permissionsor the combination of (resource_id,resource_type,raw_permissions,effective_permissions) must be provided in the request, but not both.
The API provides two options for ordering the returned grantees:
Default Order (Minimal Access Count): By default, the API returns grantees ordered by their access count, prioritizing roles with fewest total accesses.
Least Privileged: When setting "result_order": "LEAST_PRIVILEGED", the API orders grantees by least privilege principle (minimum necessary permissions) and enables several advanced features:
No system-defined admin roles will be returned in the results
The resource_permissions parameter can be used, which allows input of multiple resources
When max_resource_count is reached for an identity, the API will return grantees with the least resources by themselves, instead of those providing the least extra resources.
The no_extra_stats parameter improves performance when detailed statistics aren't needed. This parameter will:
Skip saved query lookup for grantee IDs
Only include basic resource count information in the response
Ignore the saved_query_id_for_grantee_ids parameter
Only return old_accessible_resource_count and new_accessible_resource_count for the input resource_type
This parameter is not effective when result_order is set to LEAST_PRIVILEGED
The resource_permissions parameter is only usable when result_order is set to LEAST_PRIVILEGED
The API returns a GetAccessRelationshipResponse object with the following fields:
Note: There are deprecated fields in the response (
role_id,resource_type,new_accessible_resource_count) that should not be used. Use theordered_node_access_changesfield instead.
Each NodeAccessChange object contains:
Each ResourceAccessChange object contains:
This example shows how to use the API to find roles that would give a specific Snowflake user access to certain resources using the resource_permissions parameter.
Request
This example shows how to use the API with the resource ID and permissions approach.
This example uses LEAST_PRIVILEGED result ordering. The response will prioritize grantees that provide the minimum necessary permissions to meet the requested access requirements.
Request
is a product capability allowing organizations to add additional metadata to the entities (such as users, roles, tables, or any other resource/identity) discovered by Veza.
You can filter results for entities with a given tag, create based on tags, or use them to add context and notes that other users can view and search by.
To apply a tag, you will need the ID of the node to modify. Calling will return IDs as part of the search result. You can also retrieve this value by clicking Show Details for the entity in Authorization Graph, or checking the ID column from Identity Data Entities or the Query Builder.
Generate a bearer token from .
This feature is currently limited to the .
This feature is currently limited to the .
This feature is currently limited to the .
grantee_type
string
Yes
The type of grantee for which the role existence is checked (currently supports only SnowflakeRole)
resource_permissions
ResourcePermissions[]
Yes
A list of resource permissions to match against existing roles
node_type
string
Yes
The type of resource node (supported types are SnowflakeDatabase, SnowflakeTable, SnowflakeView, and SnowflakeSchema)
node_id
string
Yes
Veza node ID of the resource (i.e., ID property in graph and query builder)
raw_permissions
string[]
Yes
A list of permissions to check (e.g., USAGE, SELECT, etc.)
grantee_ids
string[]
A list of existing role IDs that match the given permissions
grantee_type
string
Yes
The type of grantee (currently only supports SnowflakeRole)
grantee_id
string
Yes
Veza node ID of the grantee (role) to be modified
modifications
GranteeModification[]
Yes
A list of resource permission modifications to apply to the role
from_resource_permissions
ResourcePermissions
No
Permissions to remove from the role
to_resource_permissions
ResourcePermissions
No
Permissions to add to the role
node_type
string
Yes
The type of resource node (supported types are SnowflakeDatabase, SnowflakeTable, SnowflakeView, and SnowflakeSchema)
node_id
string
Yes
Veza node ID of the resource (ID property in graph and query builder)
raw_permissions
string[]
Yes
A list of permissions (e.g., USAGE, SELECT, etc.)
grantee_ids
string[]
A list of existing role IDs that match the permission set after the requested modifications
tag
body
Contains a single key:value pair
key
body
Max length 255 characters (alphanumeric and _)
value
body
Max length 4096 characters (alphanumeric, _ and ,).
node_id
body
Veza entity ID
tags
body
Array of tags to add
node_id
body
ID of the entity to modify
tag_key
body
Must contain a single tag to remove
identity_id
string
Yes
ID for the principal (user) in Veza node ID format
identity_type
string
Yes
Veza node type for the principal (currently must be SnowflakeUser)
resource_id
string
No
ID of the resource to analyze
resource_type
string
No
Type of the resource to analyze (used to calculate impact)
raw_permissions
RawPermissionCollection
No
Collection of raw permissions to analyze
effective_permissions
EffectivePermissionCollection
No
Collection of effective permissions to analyze
grantee_type
string
No
Veza node type for the grantee (currently must be SnowflakeRole)
grantee_filter
AssessmentQuerySpecFilter
No
Filter to apply on potential grantees
saved_query_id_for_grantee_ids
string
No
ID of a saved query, source nodes in its result will be used as a filter
max_grantee_count
int32
No
Maximum number of grantees to return
resource_types_to_display
string[]
No
Resource types to include in the result (in addition to resource_type above)
max_resource_count
int32
No
Grantees with access to more resources will be excluded from the results. 0 (unset) uses the default value of 100,000. Setting a higher value will include grantees with more resources.
no_extra_stats
boolean
No
Show less stats to makes the API respond faster: when True, the response will not contain permission summaries and resource access changes, but the grantee IDs are still returned in the correct order.
resource_permissions
ResourcePermissions[]
No
Only valid when result order is LEAST_PRIVILEGED. Returned grantees will be able to access all resources with the permissions in resource_permissions.
result_order
RoleRecommendationResultOrder
No
Ordering method for results (default is by minimal access count)
direct_grantee_to_resource_only
boolean
No
When true, only return roles with direct access to the input resources
ordered_node_access_changes
NodeAccessChange[]
List of grantees and their access statistics, ordered according to the input result_order
is_identity_highly_connected
boolean
Indicates if the identity has access to many resources (>10,000 accesses for a single resource type)
result_time
Timestamp
Time when the cache was refreshed (if cache was used)
identity_already_has_all_access
boolean
Indicates if the principal already has all the requested access
node_type
string
The node type of the grantee
id
string
The node ID of the grantee
name
string
The name of the grantee
resource_access_changes
ResourceAccessChange[]
Access changes per resource type
resource_type
string
Type of the resource
old_accessible_resource_count
int32
Count of resources accessible before granting
new_accessible_resource_count
int32
Count of resources accessible after granting
old_raw_permissions
string[]
List of raw permissions before granting
new_raw_permissions
string[]
List of raw permissions after granting
old_effective_permissions
string[]
List of effective permissions before granting
new_effective_permissions
string[]
List of effective permissions after granting
Operations for adding, removing, and listing tags for entity enrichment.
Tag promotion for Access Reviews is currently available in Early Access. Please contact our support team to enable this capability.
Use these APIs to define the tags Veza should treat as customer-defined properties. Access Reviews that involve these entity types will include columns showing the tag name and value.
For example, in AWS, you may automatically tag identities with a 3rd-party security tool, or use tags to label S3 buckets containing sensitive data. When a tag is promoted, Veza Access Reviews will treat the tag as a built-in entity attribute, and show this information for reviewers in an optional column.
Add a promotion rule by specifying its type and key, and the entity types it applies to:
include_entity_types: if true, promote tags for the listed type(s).
exclude_entity_type: if true, promotes tags for all entities except the listed type(s).
AWSTag
CookieTag (Veza Tag)
GoogleCloudLabel
Entity types for tag promotion should be concrete types. You can confirm the format by viewing details for any graph node, and checking the Type attribute, for example:
OAA.PagerDuty.User
ActiveDirectoryUser
OAA.custom_idp.IDPUser
Remove a promotion rule for the specified tag key and type. Demotions apply on the next data source parse.
Get all promotion rules for all entity types.
Analyze roles accessible to Snowflake users within a specified cost center.
Early Access: This API is provided in Early Access. Please contact our customer support team for more information and to enable this feature.
The Cohort Role Analysis API provides insights into role accessibility for Snowflake users within a specified cost center. It identifies which roles are accessible to users in that cost center and orders them by least privilege, helping to establish common access patterns and standardize role assignments. The response includes:
A list of roles accessible to users in the cost center
An indication of whether these roles are accessible to all users or only some users in the cost center
The API first attempts to find roles that are accessible to all principals (users) in the cost center. If no roles are accessible to all principals, it falls back to returning roles that are accessible by at least one principal, indicated by the accessibility_type field in the response.
This API can help organizations understand common access patterns within organizational units and can support role standardization efforts:
Role Standardization: Identify common roles used within organizational units
Access Pattern Analysis: Discover shared access patterns among users in the same cost center
Least Privilege Implementation: Find roles that provide necessary access with minimal permissions
Onboarding Planning: Determine appropriate roles for new hires based on their cost center
Role analysis is based on cost center information, which must be properly configured in your system.
The API accepts a request object with the following parameters:
cost_center
string
Yes
The identifier for the cost center whose roles should be analyzed
limit
uint32
No
The maximum number of roles to return (defaults to 5 if not specified)
The API uses the following protocol buffer message definitions:
The API returns a response object with the following fields:
grantee_ids
string[]
A list of role IDs that are accessible to users in the specified cost center
accessibility_type
GranteeAccessibility
Indicates whether roles were accessible to all principals or any principal
The accessibility_type field can have one of the following values:
ALL_PRINCIPALS
Roles accessible from all principals in the cost center
ANY_PRINCIPAL
Roles accessible from at least one principal in the cost center
Note: If no roles are accessible to all principals in the cost center, the API falls back to returning roles accessible by any principal, and the accessibility_type will be set to ANY_PRINCIPAL.
Request
Response
The response indicates these roles are accessible to all users in the cost center:
Request
Response
The response indicates no roles are accessible to all users, but these roles are accessible to at least one user in the cost center:
You can promote tags for any integration that supports them, such as Snowflake or Google Cloud. Use for integrations that do not support vendor-native tags or when built-in tagging is unavailable. Example tag types:
This feature is currently limited to the .
The maximum number of results to be returned. Fewer results may be returned even when more pages exist.
The token specifying the specific page of results to retrieve.
The maximum number of results to be returned. Fewer results may be returned even when more pages exist.
The token specifying the specific page of results to retrieve.
destination_node_count ASC and destination_node_count DESC are valid values
The maximum number of results to be returned. Fewer results may be returned even when more pages exist.
The token specifying the specific page of results to retrieve.
SYSTEM_CREATEDPossible values: PUBLICPossible values: EFFECTIVE_ACCESSPossible values: NONEPossible values: UNSETPossible values: PUBLICPossible values: EFFECTIVE_ACCESSPossible values: UNSETPossible values: SYSTEM_CREATEDPossible values: EFFECTIVE_ACCESSPossible values: AssessmentQueryResultValueType determines which of the fields (values or path_values) will be populated
in the resulting AssessmentQueryNodesResponse message.
UNDEFINED is a valid selection and is intended for backward compatibility.
When UNDEFINED is selected, the actual result value type will be determined by the backend (BE).
values field containing source nodes and their destination countspath_values with source and destination nodes, excluding path summary.path_values along with path summary.UNDEFINEDPossible values: The maximum number of results to be returned. Fewer results may be returned even when more pages exist.
The token specifying the specific page of results to retrieve.
The maximum number of results to be returned. Fewer results may be returned even when more pages exist.
The token specifying the specific page of results to retrieve.
Valid ordering options are destination_node_count ASC/DESC and risk_score ASC/DESC. Note: These options are used for ordering source nodes only.
SYSTEM_CREATEDPossible values: EFFECTIVE_ACCESSPossible values: AssessmentQueryResultValueType determines which of the fields (values or path_values) will be populated
in the resulting AssessmentQueryNodesResponse message.
UNDEFINED is a valid selection and is intended for backward compatibility.
When UNDEFINED is selected, the actual result value type will be determined by the backend (BE).
values field containing source nodes and their destination countspath_values with source and destination nodes, excluding path summary.path_values along with path summary.UNDEFINEDPossible values: The maximum number of results to be returned. Fewer results may be returned even when more pages exist.
The token specifying the specific page of results to retrieve.
risk_score ASC/DESC are valid values
The maximum number of results to be returned. Fewer results may be returned even when more pages exist.
The token specifying the specific page of results to retrieve.
The maximum number of results to be returned. Fewer results may be returned even when more pages exist.
The token specifying the specific page of results to retrieve.
only one of resource_permissions or (resource_id, resource_type, raw_permissions, effective_permissions) can be set in the input
When result_type=DEFAULT, setting no_extra_stats to true will also skip these queries:
result_order is by default minimal access count, but can be set to LEAST_PRIVILEGED and enable new features including resource_permissions and faster response
Adds a promoted tag. If a promoted tag with the same tag_key and tag_type already
exists, a unique constraint error will be returned without modifying the existing
promoted tag.
tag_key and tag_type specify the tag to be promoted
Only one or the other makes sense to be set. include_entity_types indicates promote only for the listed type exclude_entity_type indicates promote for any type except for the listed types The types should be concrete types, and OAA types should be supplied with their native types name, ie "OAA.ApplicationName.Type".