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

/api/private/assessments/access_relationship

Authorizations

Body

identity_idstring

identity_typestring

resource_idstring

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

resource_typestring

raw_permissionsobject

A collection of raw permission names

effective_permissionsobject

grantee_typestring

grantee_filterobject

saved_query_id_for_grantee_idsstring

max_grantee_countinteger · int32

resource_types_to_displaystring[]

max_resource_countinteger · int32

Max resource count for identity and grantee. 0 (unset) to use default value. Grantee with access to more resources will be excluded from the result. For Identity with access to more resources, response will return grantees of least resources by themselves, instead of least extra resources.

no_extra_statsboolean

This makes it respond faster by showing less stats. A few queries are made merely to display more stats:

• permission summaries
• ResourceAccessChange for extra resource types Set this to true will 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.

resource_permissionsobject[]

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

result_orderinteger · enum

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/private/assessments/access_relationship' \
  --header 'Authorization: Bearer Bearer <API key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "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": "[Circular Reference]",
        "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"
      },
      "node_relationship_type": 1,
      "relates_to_exp": "[Circular Reference]",
      "path_summary_node_types": {
        "nodes": "[Circular Reference]",
        "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
          }
        ],
        "child_expressions": "[Circular Reference]",
        "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
  }'

200

default

200

{
  "role_id": "text",
  "resource_type": "text",
  "new_accessible_resource_count": 1,
  "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-03-09T02:24:48.254Z",
  "identity_already_has_all_access": true
}

OK

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	Maximum resource count for identity and grantee analysis
no_extra_stats	boolean	No	When true, omits extra statistics for faster response
resource_permissions	ResourcePermissions[]	No	List of resources with permissions to analyze
result_order	RoleRecommendationResultOrder	No	Ordering method for results (default is by minimal access count)

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