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:

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

• This feature is currently limited to the Snowflake integration.

Role Maintenance API

post

Authorizations

bearerAuth

AuthorizationstringRequired

Veza API key for authentication. Generate keys in Administration > API Keys.

Body

application/json

grantee_typestringOptional

grantee_idstringOptional

Responses

200

OK

application/json

grantee_idsstring[]Optional

default

Default error response

application/json

post

/api/private/assessments/role_recommendations_role_maintenance

HTTPcURLJavaScriptPython

POST /api/private/assessments/role_recommendations_role_maintenance HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
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:

Parameter	Type	Required	Description
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:

Field	Type	Required	Description
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_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:

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

Field	Type	Description
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

• Get Access Relationship API

• Role Existence API

• Cohort Role Analysis API