# Cohort Role Analysis

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

* This feature is currently limited to the [Snowflake integration](/4yItIzMvkpAvMVFAamTf/integrations/integrations/snowflake.md).
* Role analysis is based on cost center information, which must be properly configured in your system.

### Cohort Role Analysis API

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/assessments/cohort\_role\_analysis" method="post" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-7fffa1b503c9e0990ac3091c19a420bf184d1dec%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Request Parameters

The API accepts a request object with the following parameters:

| Parameter     | Type   | Required | Description                                                            |
| ------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `cost_center` | string | Yes      | The identifier for the cost center whose roles should be analyzed      |
| `limit`       | uint32 | No       | The maximum number of roles to return (defaults to 5 if not specified) |

### Protocol Definition

#### Proto Message Definitions

The API uses the following protocol buffer message definitions:

```proto
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:

| Field                | Type                 | Description                                                                  |
| -------------------- | -------------------- | ---------------------------------------------------------------------------- |
| `grantee_ids`        | string\[]            | A list of role IDs that are accessible to users in the specified cost center |
| `accessibility_type` | GranteeAccessibility | Indicates whether roles were accessible to all principals or any principal   |

#### Accessibility Types

The `accessibility_type` field can have one of the following values:

| Value            | Description                                                     |
| ---------------- | --------------------------------------------------------------- |
| `ALL_PRINCIPALS` | Roles accessible from all principals in the cost center         |
| `ANY_PRINCIPAL`  | Roles accessible from at least one principal in the cost center |

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

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

**Response**

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

```json
{
  "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**

```json
{
  "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:

```json
{
  "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

* [Get Access Relationship API](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/assessments/getaccessrelationship.md)
* [Role Existence API](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/assessments/roleexistence.md)
* [Role Maintenance API](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/assessments/rolemaintenance.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/cohortroleanalysis.md?ask=<question>
```

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.