1 of 1

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.

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

Limitations

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

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

ID of the resource to analyze

resource_type

string

Type of the resource to analyze (used to calculate impact)

raw_permissions

RawPermissionCollection

Collection of raw permissions to analyze

effective_permissions

EffectivePermissionCollection

Collection of effective permissions to analyze

grantee_type

string

Veza node type for the grantee (currently must be SnowflakeRole)

grantee_filter

AssessmentQuerySpecFilter

Filter to apply on potential grantees

saved_query_id_for_grantee_ids

string

ID of a saved query, source nodes in its result will be used as a filter

max_grantee_count

int32

Maximum number of grantees to return

resource_types_to_display

string[]

Resource types to include in the result (in addition to resource_type above)

max_resource_count

int32

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

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[]

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

Ordering method for results (default is by minimal access count)

direct_grantee_to_resource_only

boolean

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
}

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

Use cases and features

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

Limitations

This feature is currently limited to the .
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

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

ID of the resource to analyze

resource_type

string

Type of the resource to analyze (used to calculate impact)

raw_permissions

RawPermissionCollection

Collection of raw permissions to analyze

effective_permissions

EffectivePermissionCollection

Collection of effective permissions to analyze

grantee_type

string

Veza node type for the grantee (currently must be SnowflakeRole)

grantee_filter

AssessmentQuerySpecFilter

Filter to apply on potential grantees

saved_query_id_for_grantee_ids

string

ID of a saved query, source nodes in its result will be used as a filter

max_grantee_count

int32

Maximum number of grantees to return

resource_types_to_display

string[]

Resource types to include in the result (in addition to resource_type above)

max_resource_count

int32

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

resource_permissions

ResourcePermissions[]

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

Ordering method for results (default is by minimal access count)

direct_grantee_to_resource_only

boolean

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
}

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

application/json

default

Default error response

application/json

post

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-25T12:51:17.146Z",
        "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-25T12:51:17.146Z",
  "identity_already_has_all_access": true
}

Get Access Relationship

Overview

Use cases and features

Limitations

Get Access Relationship

Request Parameters

Result Ordering

Special Considerations

Response Structure

NodeAccessChange Structure

ResourceAccessChange Structure

Usage Examples

Example 1: Using Resource Permissions (Recommended)

Example 2: Using Resource ID and Permissions

Response

Related APIs

Get Access Relationship

Overview

Use cases and features

Limitations

Get Access Relationship

Request Parameters

Result Ordering

Special Considerations

Response Structure

NodeAccessChange Structure

ResourceAccessChange Structure

Usage Examples

Example 1: Using Resource Permissions (Recommended)

Example 2: Using Resource ID and Permissions

Response

Related APIs