# Get Access Relationship > **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](/4yItIzMvkpAvMVFAamTf/integrations/integrations/snowflake.md). * 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 {% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/assessments/access\_relationship" method="post" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media) {% endopenapi %} ### 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** ```json { "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** ```json { "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 ```json { "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](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/assessments/roleexistence.md) * [Role Maintenance API](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/assessments/rolemaintenance.md) * [Cohort Role Analysis API](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/assessments/cohortroleanalysis.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/assessments/getaccessrelationship.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.