Role Existence
Check whether a role with specific resource permissions already exists.
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:
Role Discovery: Find existing roles that match specific permission requirements
Prevent Role Proliferation: Avoid creating duplicate roles with the same permissions
Permission Auditing: Verify which roles have specific permissions to resources
Role Standardization: Identify standard roles that can be reused for similar access requirements
Limitations
This feature is currently limited to the Snowflake integration.
Role Existence API
POST /api/private/assessments/role_recommendations_role_exists HTTP/1.1
Host:
Authorization: Bearer Bearer <API key>
Content-Type: application/json
Accept: */*
Content-Length: 113
{
"grantee_type": "text",
"resource_permissions": [
{
"raw_permissions": [
"text"
],
"node_type": "text",
"node_id": "text"
}
]
}{
"grantee_ids": [
"text"
]
}Request Parameters
The API accepts a request object with the following parameters:
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:
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:
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:
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:
{
"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
Last updated
Was this helpful?