Get Access Relationship

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.

Overview

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.

Use cases and features

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.

1. Role Recommendations: Find the most appropriate roles to grant a user for specific access needs

2. Privilege Analysis: Analyze what additional privileges different roles would provide to a user

3. Access Management: Compare different access options before making permission changes

4. Least Privilege Implementation: Identify roles that provide necessary access with minimal excess permissions

Limitations

• This feature is currently limited to the Snowflake integration.

• 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.

Get Access Relationship

post

Authorizations

Body

identity_idstringOptional

identity_typestringOptional

resource_idstringOptional

only one of resource_permissions or (resource_id, resource_type, raw_permissions, effective_permissions) can be set in the input

resource_typestringOptional

grantee_typestringOptional

saved_query_id_for_grantee_idsstringOptional

max_grantee_countinteger · int32Optional

resource_types_to_displaystring[]Optional

max_resource_countinteger · int32Optional

no_extra_statsbooleanOptional

When result_type=DEFAULT, setting no_extra_stats to true will also skip these queries:

• saved_query_id_for_grantee_ids will be ignored
• response will only contain old_accessible_resource_count and new_accessible_resource_count for input resource_type.

result_orderinteger · enumOptional

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

direct_grantee_to_resource_onlybooleanOptional

Responses

200

OK

application/json

default

Default error response

application/json

post

HTTPcURLJavaScriptPython

POST /api/private/assessments/access_relationship HTTP/1.1
Host: 
Authorization: Bearer Bearer <API key>
Content-Type: application/json
Accept: */*
Content-Length: 3575

{
  "identity_id": "text",
  "identity_type": "text",
  "resource_id": "text",
  "resource_type": "text",
  "raw_permissions": {
    "values": [
      "text"
    ],
    "operator": 1
  },
  "effective_permissions": {
    "values": [
      1
    ],
    "operator": 1
  },
  "grantee_type": "text",
  "grantee_filter": {
    "query_type": 1,
    "source_node_types": {
      "nodes": [
        {
          "node_type": "text",
          "condition_expression": {
            "specs": [
              {
                "fn": 1,
                "property": "text",
                "value": null,
                "not": true,
                "value_property_name": "text",
                "value_property_from_other_node": true
              }
            ],
            "tag_specs": [
              {
                "tag": {
                  "type": "text",
                  "key": "text",
                  "value": "text",
                  "properties": {
                    "ANY_ADDITIONAL_PROPERTY": null
                  }
                },
                "exclude": true
              }
            ],
            "child_expressions": "[Circular Reference]",
            "operator": 1,
            "not": true
          },
          "node_id": "text",
          "count_condition_expression": "[Circular Reference]",
          "direct_relationship_only": true,
          "node_type_grouping_constraint": {
            "node_types": [
              "text"
            ],
            "constraint_type": 1
          },
          "properties_to_get": [
            "text"
          ],
          "tags_to_get": [
            {
              "type": 1,
              "key": "text"
            }
          ],
          "integration_types": [
            "text"
          ]
        }
      ],
      "nodes_operator": 1
    },
    "customized_variables": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "access_filter": {
      "engagement_score": {
        "op": 1,
        "value": 1
      },
      "over_provisioned_score": {
        "op": 1,
        "value": 1
      },
      "include_secondary_grantee": true,
      "include_indirect_resource": true,
      "exclude_indirect_grantee": true,
      "anomaly_detection_history_days": "text",
      "last_used": {
        "op": 1,
        "value": "2025-05-02T19:24:02.215Z",
        "target": 1
      }
    },
    "node_relationship_type": 1,
    "relates_to_exp": {
      "specs": [
        {
          "node_types": "[Circular Reference]",
          "required_intermediate_node_types": "[Circular Reference]",
          "avoided_intermediate_node_types": "[Circular Reference]",
          "raw_permissions": {
            "values": [
              "text"
            ],
            "operator": 1
          },
          "effective_permissions": {
            "values": [
              1
            ],
            "operator": 1
          },
          "no_relation": true,
          "direction": 1
        }
      ],
      "child_expressions": [
        {
          "specs": "[Circular Reference]",
          "child_expressions": "[Circular Reference]",
          "operator": 1,
          "not": true,
          "and_op_type": 1
        }
      ],
      "operator": 1,
      "not": true,
      "and_op_type": 1
    },
    "path_summary_node_types": {
      "nodes": [
        {
          "node_type": "text",
          "condition_expression": {
            "specs": [
              {
                "fn": 1,
                "property": "text",
                "value": null,
                "not": true,
                "value_property_name": "text",
                "value_property_from_other_node": true
              }
            ],
            "tag_specs": [
              {
                "tag": {
                  "type": "text",
                  "key": "text",
                  "value": "text",
                  "properties": {
                    "ANY_ADDITIONAL_PROPERTY": null
                  }
                },
                "exclude": true
              }
            ],
            "child_expressions": "[Circular Reference]",
            "operator": 1,
            "not": true
          },
          "node_id": "text",
          "count_condition_expression": "[Circular Reference]",
          "direct_relationship_only": true,
          "node_type_grouping_constraint": {
            "node_types": [
              "text"
            ],
            "constraint_type": 1
          },
          "properties_to_get": [
            "text"
          ],
          "tags_to_get": [
            {
              "type": 1,
              "key": "text"
            }
          ],
          "integration_types": [
            "text"
          ]
        }
      ],
      "nodes_operator": 1
    },
    "all_entity_condition": {
      "specs": [
        {
          "fn": 1,
          "property": "text",
          "value": null,
          "not": true,
          "value_property_name": "text",
          "value_property_from_other_node": true
        }
      ],
      "tag_specs": [
        {
          "tag": {
            "type": "text",
            "key": "text",
            "value": "text",
            "properties": {
              "ANY_ADDITIONAL_PROPERTY": null
            }
          },
          "exclude": true
        }
      ],
      "child_expressions": [
        {
          "specs": [
            {
              "fn": 1,
              "property": "text",
              "value": null,
              "not": true,
              "value_property_name": "text",
              "value_property_from_other_node": true
            }
          ],
          "tag_specs": [
            {
              "tag": {
                "type": "text",
                "key": "text",
                "value": "text",
                "properties": {
                  "ANY_ADDITIONAL_PROPERTY": null
                }
              },
              "exclude": true
            }
          ],
          "child_expressions": [
            "[Circular Reference]"
          ],
          "operator": 1,
          "not": true
        }
      ],
      "operator": 1,
      "not": true
    },
    "path_summary_count_conditions": {
      "conditions": [
        {
          "fn": 1,
          "value": "text",
          "value_as": 1
        }
      ]
    },
    "result_value_type": 1
  },
  "saved_query_id_for_grantee_ids": "text",
  "max_grantee_count": 1,
  "resource_types_to_display": [
    "text"
  ],
  "max_resource_count": 1,
  "no_extra_stats": true,
  "resource_permissions": [
    {
      "raw_permissions": [
        "text"
      ],
      "node_type": "text",
      "node_id": "text"
    }
  ],
  "result_order": 1,
  "direct_grantee_to_resource_only": true
}

{
  "ordered_node_access_changes": [
    {
      "node_type": "text",
      "id": "text",
      "name": "text",
      "resource_access_changes": [
        {
          "resource_type": "text",
          "old_accessible_resource_count": 1,
          "new_accessible_resource_count": 1,
          "old_raw_permissions": [
            "text"
          ],
          "new_raw_permissions": [
            "text"
          ],
          "old_effective_permissions": [
            "text"
          ],
          "new_effective_permissions": [
            "text"
          ]
        }
      ]
    }
  ],
  "is_identity_highly_connected": true,
  "result_time": "2025-05-02T19:24:02.215Z",
  "identity_already_has_all_access": true
}

Request Parameters

The API accepts a GetAccessRelationshipRequest object with the following parameters:

Parameter	Type	Required	Description
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

Important: Either resource_permissions or the combination of (resource_id, resource_type, raw_permissions, effective_permissions) must be provided in the request, but not both.

Result Ordering

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

Special Considerations

• 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

Response Structure

The API returns a GetAccessRelationshipResponse object with the following fields:

Field	Type	Description
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

Note: There are deprecated fields in the response (role_id, resource_type, new_accessible_resource_count) that should not be used. Use the ordered_node_access_changes field instead.

NodeAccessChange Structure

Each NodeAccessChange object contains:

Field	Type	Description
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

ResourceAccessChange Structure

Each ResourceAccessChange object contains:

Field	Type	Description
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

Usage Examples

Example 1: Using Resource Permissions (Recommended)

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

{
  "identity_id": "example-snowflake.com/user/ALICE",
  "identity_type": "SnowflakeUser",
  "resource_permissions": [
    {
      "resource_id": "example-snowflake.com/database/SALES/schema/PUBLIC/table/CUSTOMER_DATA",
      "resource_type": "SnowflakeTable",
      "permissions": ["SELECT", "INSERT"]
    }
  ],
  "grantee_type": "SnowflakeRole",
  "max_grantee_count": 5,
  "result_order": "LEAST_PRIVILEGED"
}

Example 2: Using Resource ID and Permissions

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

{
  "identity_id": "example-snowflake.com/user/ALICE",
  "identity_type": "SnowflakeUser",
  "resource_id": "example-snowflake.com/database/SALES/schema/PUBLIC/table/CUSTOMER_DATA",
  "resource_type": "SnowflakeTable",
  "raw_permissions": {
    "values": ["SELECT", "INSERT"],
    "operator": "AND"
  },
  "grantee_type": "SnowflakeRole",
  "max_grantee_count": 5,
  "result_order": "LEAST_PRIVILEGED"
}

Response

{
  "ordered_node_access_changes": [
    {
      "node_type": "SnowflakeRole",
      "id": "example-snowflake.com/role/ANALYST",
      "name": "ANALYST",
      "resource_access_changes": [
        {
          "resource_type": "SnowflakeTable",
          "old_accessible_resource_count": 10,
          "new_accessible_resource_count": 25,
          "old_raw_permissions": ["SELECT"],
          "new_raw_permissions": ["SELECT", "INSERT"],
          "old_effective_permissions": ["SELECT"],
          "new_effective_permissions": ["SELECT", "INSERT"]
        }
      ]
    },
    {
      "node_type": "SnowflakeRole",
      "id": "example-snowflake.com/role/DATA_EDITOR",
      "name": "DATA_EDITOR",
      "resource_access_changes": [
        {
          "resource_type": "SnowflakeTable",
          "old_accessible_resource_count": 10,
          "new_accessible_resource_count": 32,
          "old_raw_permissions": ["SELECT"],
          "new_raw_permissions": ["SELECT", "INSERT", "UPDATE"],
          "old_effective_permissions": ["SELECT"],
          "new_effective_permissions": ["SELECT", "INSERT", "UPDATE"]
        }
      ]
    }
  ],
  "is_identity_highly_connected": false,
  "result_time": "2025-02-25T10:15:30Z",
  "identity_already_has_all_access": false
}

Related APIs

• Role Existence API
• Role Maintenance API
• Cohort Role Analysis API