# Role Existence

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

* This feature is currently limited to the [Snowflake integration](/4yItIzMvkpAvMVFAamTf/integrations/integrations/snowflake.md).

### Role Existence API

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/assessments/role\_recommendations\_role\_exists" 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                                                                                           |
| ---------------------- | ---------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `grantee_type`         | string                 | Yes      | The type of grantee for which the role existence is checked (currently supports only `SnowflakeRole`) |
| `resource_permissions` | ResourcePermissions\[] | Yes      | A list of resource permissions to match against existing roles                                        |

#### ResourcePermissions Structure

Each `ResourcePermissions` object contains:

| Field             | Type      | Required | Description                                                                                                                   |
| ----------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `node_type`       | string    | Yes      | The type of resource node (supported types are `SnowflakeDatabase`, `SnowflakeTable`, `SnowflakeView`, and `SnowflakeSchema`) |
| `node_id`         | string    | Yes      | Veza node ID of the resource (i.e., ID property in graph and query builder)                                                   |
| `raw_permissions` | string\[] | Yes      | A list of permissions to check (e.g., `USAGE`, `SELECT`, etc.)                                                                |

### Protocol Definition

#### Proto Message Definitions

The API uses the following protocol buffer message definitions:

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

| Field         | Type      | Description                                                  |
| ------------- | --------- | ------------------------------------------------------------ |
| `grantee_ids` | string\[] | A list of existing role IDs that match the given permissions |

### Usage Example

#### Request

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

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

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

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

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

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

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

* [Get Access Relationship API](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/assessments/getaccessrelationship.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/roleexistence.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.