Role Maintenance
Modify role permissions and find matching existing roles.
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:
Role Rationalization: Find existing roles that match a desired permission set after modifications
Role Consolidation: Identify opportunities to consolidate roles by checking for existing roles with similar permissions
Permission Planning: Plan permission changes and identify existing alternatives before implementation
Access Governance: Maintain a minimal set of roles by identifying functionally equivalent roles
Limitations
This feature is currently limited to the Snowflake integration.
Role Maintenance API
POST /api/private/assessments/role_recommendations_role_maintenance HTTP/1.1
Host:
Authorization: Bearer Bearer <API key>
Content-Type: application/json
Accept: */*
Content-Length: 247
{
"grantee_type": "text",
"grantee_id": "text",
"modifications": [
{
"from_resource_permissions": {
"raw_permissions": [
"text"
],
"node_type": "text",
"node_id": "text"
},
"to_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 (currently only supports SnowflakeRole)
grantee_id
string
Yes
Veza node ID of the grantee (role) to be modified
modifications
GranteeModification[]
Yes
A list of resource permission modifications to apply to the role
GranteeModification Structure
Each GranteeModification object contains:
from_resource_permissions
ResourcePermissions
No
Permissions to remove from the role
to_resource_permissions
ResourcePermissions
No
Permissions to add to the role
Note: You can specify either or both of these fields:
If only
from_resource_permissionsis set, those permissions will be removedIf only
to_resource_permissionsis set, those permissions will be addedIf 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:
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 (ID property in graph and query builder)
raw_permissions
string[]
Yes
A list of permissions (e.g., USAGE, SELECT, etc.)
Request and Response Protocol
Proto Message Definitions
The API uses the following protocol buffer message definitions:
message RoleMaintenanceRequest {
string grantee_type = 1;
string grantee_id = 2;
repeated GranteeModification modifications = 3;
}
message GranteeModification {
GetRoleMatchingRequest.ResourcePermissions from_resource_permissions = 1;
GetRoleMatchingRequest.ResourcePermissions to_resource_permissions = 2;
}
message RoleMaintenanceResponse {
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 permission set after the requested modifications
Usage Example
Request
This example simulates removing database and schema permissions from one role while adding database permissions to another:
{
"grantee_type": "SnowflakeRole",
"grantee_id": "example-snowflake.com/role/DATA_INGEST_ROLE",
"modifications": [
{
"from_resource_permissions": {
"node_type": "SnowflakeDatabase",
"node_id": "example-snowflake.com/database/ANALYTICS_DB",
"raw_permissions": ["USAGE"]
}
},
{
"from_resource_permissions": {
"node_type": "SnowflakeSchema",
"node_id": "example-snowflake.com/database/ANALYTICS_DB/schema/RAW_DATA",
"raw_permissions": ["CREATE FUNCTION", "CREATE PIPE", "CREATE STREAM", "CREATE TABLE", "CREATE TASK", "USAGE"]
}
},
{
"to_resource_permissions": {
"node_type": "SnowflakeDatabase",
"node_id": "example-snowflake.com/database/CLOUD_DB",
"raw_permissions": ["USAGE"]
}
}
]
}Response
The response indicates that a role with the resulting permission set exists:
{
"grantee_ids": [
"example-snowflake.com/role/CLOUD_LOGS_READONLY_ROLE"
]
}Example: Adding permissions only
This example shows adding permissions to a role:
Request
{
"grantee_type": "SnowflakeRole",
"grantee_id": "example-snowflake.com/role/ANALYST_BASIC_ROLE",
"modifications": [
{
"to_resource_permissions": {
"node_type": "SnowflakeSchema",
"node_id": "example-snowflake.com/database/ANALYTICS/schema/FINANCE",
"raw_permissions": ["USAGE", "SELECT"]
}
}
]
}Response
{
"grantee_ids": [
"example-snowflake.com/role/FINANCE_VIEWER_ROLE"
]
}Example: Removing permissions only
This example shows removing permissions from a role:
Request
{
"grantee_type": "SnowflakeRole",
"grantee_id": "snowhouse.snowflakecomputing.com/role/DATA_SCIENTIST",
"modifications": [
{
"from_resource_permissions": {
"node_type": "SnowflakeSchema",
"node_id": "snowhouse.snowflakecomputing.com/database/SENSITIVE_DATA/schema/PII",
"raw_permissions": ["SELECT", "INSERT"]
}
}
]
}Response
{
"grantee_ids": [
"snowhouse.snowflakecomputing.com/role/ANALYST_BASIC"
]
}Related APIs
Last updated
Was this helpful?