> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/assessments/rolemaintenance.md). # Role Maintenance > **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](/4yItIzMvkpAvMVFAamTf/integrations/integrations/snowflake.md). ### Role Maintenance API {% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/assessments/role\_recommendations\_role\_maintenance" method="post" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-0d9d5973a247f0dc34943ed932d00eb6f5a41e3e%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 (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: ```proto 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: ```json { "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: ```json { "grantee_ids": [ "example-snowflake.com/role/CLOUD_LOGS_READONLY_ROLE" ] } ``` ### Example: Adding permissions only This example shows adding permissions to a role: #### Request ```json { "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 ```json { "grantee_ids": [ "example-snowflake.com/role/FINANCE_VIEWER_ROLE" ] } ``` ### Example: Removing permissions only This example shows removing permissions from a role: #### Request ```json { "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 ```json { "grantee_ids": [ "snowhouse.snowflakecomputing.com/role/ANALYST_BASIC" ] } ``` ### 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) * [Cohort Role Analysis API](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/assessments/cohortroleanalysis.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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/rolemaintenance.md?ask= ``` 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.