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

Use cases and features

This API can help organizations understand common access patterns within organizational units and can support role standardization efforts:

1. Role Standardization: Identify common roles used within organizational units

2. Access Pattern Analysis: Discover shared access patterns among users in the same cost center

3. Least Privilege Implementation: Find roles that provide necessary access with minimal permissions

4. Onboarding Planning: Determine appropriate roles for new hires based on their cost center

Limitations

• Role analysis is based on cost center information, which must be properly configured in your system.

Cohort Role Analysis API

Request Parameters

The API accepts a request object with the following parameters:

Protocol Definition

Proto Message Definitions

The API uses the following protocol buffer message definitions:

message CohortRoleAnalysisRequest {
  string cost_center = 1;
  uint32 limit = 2;
}

enum GranteeAccessibility {
  ALL_PRINCIPALS = 0; // Grantees accessible from all principals
  ANY_PRINCIPAL = 1;  // Grantees accessible from at least one principal
}

message CohortRoleAnalysisResponse {
  repeated string grantee_ids = 1;
  GranteeAccessibility accessibility_type = 2;
}

Response Structure

The API returns a response object with the following fields:

Accessibility Types

The accessibility_type field can have one of the following values:

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.

Usage Example

Example 1: Roles Accessible to All Principals

Request

{
  "cost_center": "CC-SALES",
  "limit": 5
}

Response

The response indicates these roles are accessible to all users in the cost center:

{
  "grantee_ids": [
    "example-snowflake.com/role/WORKSPACE_LOGS_ROLE",
    "example-snowflake.com/role/DATA_LINEAGE_READONLY_ROLE",
    "example-snowflake.com/role/WAREHOUSE_USER_ROLE"
  ],
  "accessibility_type": "ALL_PRINCIPALS"
}

Example 2: Roles Accessible to Any Principal

Request

{
  "cost_center": "CC-MARKETING"
}

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:

{
  "grantee_ids": [
    "example-snowflake.com/role/MARKETING_PARTNER_READONLY_ROLE",
    "example-snowflake.com/role/MARKETING_ENTERPRISE_READONLY_ROLE",
    "example-snowflake.com/role/WORKSPACE_LOGS_ROLE",
    "example-snowflake.com/role/MARKETING_PRODUCT_READONLY_ROLE",
    "example-snowflake.com/role/MARKETING_UTILS_READONLY_ROLE"
  ],
  "accessibility_type": "ANY_PRINCIPAL"
}

Related APIs

Overview

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.

Available APIs

Common Use Cases

These APIs enable several identity security use cases:

1. Role Rationalization: Identify and consolidate redundant roles to simplify access management

2. Least Privilege Implementation: Find roles that provide necessary access with minimal excess permissions

3. Access Governance: Maintain a minimal set of roles by identifying functionally equivalent roles

4. Access Pattern Analysis: Discover common access patterns among users in the same organizational unit

5. Privileged Access Management: Analyze what additional privileges different roles would provide to a user

Limitations

• Some APIs may have performance limitations with highly connected identities or complex permission structures.

Related Documentation

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

Use cases and features

This API enables effective role maintenance and governance with several key capabilities:

1. Role Rationalization: Find existing roles that match a desired permission set after modifications

2. Role Consolidation: Identify opportunities to consolidate roles by checking for existing roles with similar permissions

3. Permission Planning: Plan permission changes and identify existing alternatives before implementation

4. Access Governance: Maintain a minimal set of roles by identifying functionally equivalent roles

Limitations

Role Maintenance API

Request Parameters

The API accepts a request object with the following parameters:

GranteeModification Structure

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.

ResourcePermissions Structure

Each ResourcePermissions object contains:

Request and Response Protocol

Proto Message Definitions

The API uses the following protocol buffer message definitions:

Response Structure

The API returns a response object with the following field:

Usage Example

Request

This example simulates removing database and schema permissions from one role while adding database permissions to another:

Response

The response indicates that a role with the resulting permission set exists:

Example: Adding permissions only

This example shows adding permissions to a role:

Request

Response

Example: Removing permissions only

This example shows removing permissions from a role:

Request

Response

Related APIs

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

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

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:

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:

ResourceAccessChange Structure

Each ResourceAccessChange object contains:

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

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

Use cases and features

This API enables efficient role management by identifying existing roles that already have the permissions you're looking for. Key use cases include:

1. Role Discovery: Find existing roles that match specific permission requirements

2. Prevent Role Proliferation: Avoid creating duplicate roles with the same permissions

3. Permission Auditing: Verify which roles have specific permissions to resources

4. Role Standardization: Identify standard roles that can be reused for similar access requirements

Limitations

Role Existence API

Request Parameters

The API accepts a request object with the following parameters:

ResourcePermissions Structure

Each ResourcePermissions object contains:

Protocol Definition

Proto Message Definitions

The API uses the following protocol buffer message definitions:

message RoleExistsRequest {
  string grantee_type = 1;
  repeated GetRoleMatchingRequest.ResourcePermissions resource_permissions = 2;
}

message RoleExistsResponse {
  repeated string grantee_ids = 1;
}

Response Structure

The API returns a response object with the following field:

Usage Example

Request

This example checks if there's an existing role with USAGE permission on a specific Snowflake database:

{
  "grantee_type": "SnowflakeRole",
  "resource_permissions": [
    {
      "node_type": "SnowflakeDatabase",
      "node_id": "example-snowflake.com/database/SECURITY_DB",
      "raw_permissions": ["USAGE"]
    }
  ]
}

Response

The response indicates that a matching role exists:

{
  "grantee_ids": [
    "example-snowflake.com/role/SECURITY_READER_ROLE"
  ]
}

Example: Multiple Resource Permissions

You can check for roles that have permissions across multiple resources:

Request

{
  "grantee_type": "SnowflakeRole",
  "resource_permissions": [
    {
      "node_type": "SnowflakeDatabase",
      "node_id": "example-snowflake.com/database/ANALYTICS",
      "raw_permissions": ["USAGE"]
    },
    {
      "node_type": "SnowflakeSchema",
      "node_id": "example-snowflake.com/database/ANALYTICS/schema/PUBLIC",
      "raw_permissions": ["USAGE", "SELECT"]
    }
  ]
}

Response

{
  "grantee_ids": [
    "example-snowflake.com/role/ANALYTICS_READER_ROLE",
    "example-snowflake.com/role/REPORTING_USER_ROLE"
  ]
}

Example: No Matching Roles

In this example, the request is checking for roles with specific permissions, but no matching roles are found:

Request

{
  "grantee_type": "SnowflakeRole",
  "resource_permissions": [
    {
      "node_type": "SnowflakeDatabase",
      "node_id": "snowhouse.snowflakecomputing.com/database/RESEARCH_DATA",
      "raw_permissions": ["OWNERSHIP"]
    },
    {
      "node_type": "SnowflakeSchema",
      "node_id": "snowhouse.snowflakecomputing.com/database/RESEARCH_DATA/schema/EXPERIMENTS",
      "raw_permissions": ["CREATE TABLE", "CREATE VIEW", "MODIFY"]
    }
  ]
}

Response

The response indicates that no matching roles with the specified permission combination exist:

{
  "grantee_ids": []
}

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.

Related APIs