# Roles

The Roles API allows administrators to define and manage roles within the NVIDIA Run:ai platform. A role represents a collection of permission sets that determine what actions can be performed across NVIDIA Run:ai resources. NVIDIA Run:ai provides a list of predefined roles that cover common operational needs, such as managing workloads, projects, or data and storage. Administrators can also use this API to create custom roles by combining specific permission sets to match their organization's access model.

## Get a list of roles.

> Use to retrieve a list of roles. This endpoint is deprecated and will be removed in a future release. Use GET /api/v2/authorization/roles instead.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Roles","description":"The Roles API allows administrators to define and manage roles within the NVIDIA Run:ai platform. \nA role represents a collection of permission sets that determine what actions can be performed across NVIDIA Run:ai resources.\nNVIDIA Run:ai provides a list of predefined roles that cover common operational needs, such as managing workloads, projects, or data and storage. \nAdministrators can also use this API to create custom roles by combining specific permission sets to match their organization's access model.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"schemas":{"RolesV1":{"type":"array","items":{"$ref":"#/components/schemas/RoleV1"}},"RoleV1":{"type":"object","required":["name","description","permissions","id","createdAt","updatedAt","createdBy","custom","effectiveEnabled"],"properties":{"id":{"type":"integer","format":"int32"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","nullable":true,"format":"date-time"},"createdBy":{"type":"string"},"custom":{"type":"boolean"},"effectiveEnabled":{"type":"boolean","default":true},"permissions":{"$ref":"#/components/schemas/Permissions"},"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean","default":true,"nullable":true},"kubernetesPermissions":{"$ref":"#/components/schemas/KubernetesPermissions"}}},"Permissions":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}},"Permission":{"type":"object","required":["resourceType","actions","groupId","displayName"],"properties":{"resourceType":{"$ref":"#/components/schemas/ResourceType"},"displayName":{"type":"string"},"groupId":{"$ref":"#/components/schemas/ResourceTypeGroupId"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/Action"}}}},"ResourceType":{"type":"string","description":"Resource type enum for authorization. \n\nNote: The 'apps' resource type is DEPRECATED. Please use 'service-account' instead for managing service accounts.\n","enum":["department","tenant","project","cluster","cluster-config","nodepools","nodes","settings","security-settings","branding-settings","users","apps","service-account","dashboards-overview","dashboards-analytics","dashboards-consumption","roles","access_rules","workloads","workspaces","trainings","inferences","environments","pvc-assets","git-assets","host-path-assets","nfs-assets","s3-assets","compute-resources","templates","credentials","events-history","policies","cm-volume-assets","datavolumes","secret-volume-assets","storage-class-configuration","access-keys","workload-properties","network-topologies","registries","workload-integration-metrics","nodepools-minimal","clusters-minimal"]},"ResourceTypeGroupId":{"type":"string","enum":["organization","physical-resource","iam","dashboard","workload","workload-asset"]},"Action":{"type":"string","enum":["create","read","update","delete","sync"]},"KubernetesPermissions":{"type":"object","properties":{"predefinedRole":{"type":"string","description":"The ID of an NVIDIA Run:ai predefined role. The custom role will include the mapped Kubernetes ClusterRole and its permissions.","nullable":true}}},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/authorization/roles":{"get":{"summary":"Get a list of roles.","description":"Use to retrieve a list of roles. This endpoint is deprecated and will be removed in a future release. Use GET /api/v2/authorization/roles instead.","operationId":"get_roles_v1","deprecated":true,"tags":["Roles"],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RolesV1"}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Get a role by id.

> Retrieve the details of a role by id. This endpoint is deprecated and will be removed in a future release. Use GET /api/v2/authorization/roles/{roleIdPath} instead.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Roles","description":"The Roles API allows administrators to define and manage roles within the NVIDIA Run:ai platform. \nA role represents a collection of permission sets that determine what actions can be performed across NVIDIA Run:ai resources.\nNVIDIA Run:ai provides a list of predefined roles that cover common operational needs, such as managing workloads, projects, or data and storage. \nAdministrators can also use this API to create custom roles by combining specific permission sets to match their organization's access model.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"RoleIdPath":{"name":"roleIdPath","in":"path","required":true,"description":"The ID of the role","schema":{"type":"integer","format":"int32","minimum":0}}},"schemas":{"RoleV1":{"type":"object","required":["name","description","permissions","id","createdAt","updatedAt","createdBy","custom","effectiveEnabled"],"properties":{"id":{"type":"integer","format":"int32"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","nullable":true,"format":"date-time"},"createdBy":{"type":"string"},"custom":{"type":"boolean"},"effectiveEnabled":{"type":"boolean","default":true},"permissions":{"$ref":"#/components/schemas/Permissions"},"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean","default":true,"nullable":true},"kubernetesPermissions":{"$ref":"#/components/schemas/KubernetesPermissions"}}},"Permissions":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}},"Permission":{"type":"object","required":["resourceType","actions","groupId","displayName"],"properties":{"resourceType":{"$ref":"#/components/schemas/ResourceType"},"displayName":{"type":"string"},"groupId":{"$ref":"#/components/schemas/ResourceTypeGroupId"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/Action"}}}},"ResourceType":{"type":"string","description":"Resource type enum for authorization. \n\nNote: The 'apps' resource type is DEPRECATED. Please use 'service-account' instead for managing service accounts.\n","enum":["department","tenant","project","cluster","cluster-config","nodepools","nodes","settings","security-settings","branding-settings","users","apps","service-account","dashboards-overview","dashboards-analytics","dashboards-consumption","roles","access_rules","workloads","workspaces","trainings","inferences","environments","pvc-assets","git-assets","host-path-assets","nfs-assets","s3-assets","compute-resources","templates","credentials","events-history","policies","cm-volume-assets","datavolumes","secret-volume-assets","storage-class-configuration","access-keys","workload-properties","network-topologies","registries","workload-integration-metrics","nodepools-minimal","clusters-minimal"]},"ResourceTypeGroupId":{"type":"string","enum":["organization","physical-resource","iam","dashboard","workload","workload-asset"]},"Action":{"type":"string","enum":["create","read","update","delete","sync"]},"KubernetesPermissions":{"type":"object","properties":{"predefinedRole":{"type":"string","description":"The ID of an NVIDIA Run:ai predefined role. The custom role will include the mapped Kubernetes ClusterRole and its permissions.","nullable":true}}},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/authorization/roles/{roleIdPath}":{"get":{"summary":"Get a role by id.","description":"Retrieve the details of a role by id. This endpoint is deprecated and will be removed in a future release. Use GET /api/v2/authorization/roles/{roleIdPath} instead.","operationId":"get_role_v1","deprecated":true,"tags":["Roles"],"parameters":[{"$ref":"#/components/parameters/RoleIdPath"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleV1"}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Get a list of roles.

> Retrieves a list of all available roles, including both NVIDIA Run:ai predefined roles and custom roles. Use this endpoint to review role configurations, permission sets and permissions.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Roles","description":"The Roles API allows administrators to define and manage roles within the NVIDIA Run:ai platform. \nA role represents a collection of permission sets that determine what actions can be performed across NVIDIA Run:ai resources.\nNVIDIA Run:ai provides a list of predefined roles that cover common operational needs, such as managing workloads, projects, or data and storage. \nAdministrators can also use this API to create custom roles by combining specific permission sets to match their organization's access model.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"Limit":{"name":"limit","in":"query","required":false,"description":"The maximum number of entries to return.","schema":{"type":"integer","format":"int32","default":50,"minimum":1,"maximum":500}},"Offset":{"name":"offset","in":"query","required":false,"description":"The offset of the first item returned in the collection.","schema":{"type":"integer","format":"int32"}},"SortOrder":{"name":"sortOrder","in":"query","required":false,"description":"Sort results in descending or ascending order.","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}},"RolesSort":{"name":"sortBy","in":"query","required":false,"description":"Sort results by a parameter.","schema":{"$ref":"#/components/schemas/RolesSortFilterFields"}},"RolesFilter":{"name":"filterBy","in":"query","required":false,"description":"Filter results by a parameter. Use the format field-name operator value. Operators are == Equals, != Not equals, <= Less than or equal, >= Greater than or equal, =@ contains, !@ Does not contains, =^ Starts with and =$ Ends with. Dates are in ISO 8601 timestamp format and available for operators ==, !=, <= and >=.","schema":{"type":"array","items":{"type":"string","pattern":"^(name|createdAt|createdBy|custom|scopeType|enabled)(==|!=|<=|>=|=@|!@|=\\^|=\\$).+$"}},"explode":false},"Search":{"name":"search","in":"query","required":false,"description":"Filter results by a free text search.","schema":{"type":"string"}}},"schemas":{"RolesSortFilterFields":{"type":"string","enum":["name","createdAt","createdBy","custom","scopeType","enabled"]},"Roles":{"type":"array","items":{"$ref":"#/components/schemas/Role1"}},"Role1":{"allOf":[{"$ref":"#/components/schemas/RoleCreationFields"},{"$ref":"#/components/schemas/RoleCalculatedFields"}]},"RoleCreationFields":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string","description":"The name of the role to create. Must be unique within the given scope.","minLength":1},"description":{"type":"string","description":"A description of the role."},"enabled":{"type":"boolean","default":true,"description":"Specifies whether the role is active. Default: true","nullable":true},"permissionSets":{"type":"array","description":"The permission sets assigned to this role. Each item includes the UUID and name of the permission set.","items":{"$ref":"#/components/schemas/RolePermissionSet"}},"kubernetesPermissions":{"allOf":[{"$ref":"#/components/schemas/KubernetesPermissions"}],"description":"Defines the Kubernetes cluster permissions associated with this role."}}},"RolePermissionSet":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"The universally unique ID (UUID) of the permission set."},"name":{"type":"string","description":"The name of the permission set."}}},"KubernetesPermissions":{"type":"object","properties":{"predefinedRole":{"type":"string","description":"The ID of an NVIDIA Run:ai predefined role. The custom role will include the mapped Kubernetes ClusterRole and its permissions.","nullable":true}}},"RoleCalculatedFields":{"type":"object","required":["id","createdAt","updatedAt","createdBy","custom","effectiveEnabled","permissions"],"properties":{"id":{"type":"integer","format":"int32","description":"The ID of the role."},"createdAt":{"type":"string","description":"The timestamp for when the role was created.","format":"date-time"},"updatedAt":{"type":"string","description":"The timestamp for the last time the role was updated.","format":"date-time"},"createdBy":{"type":"string","description":"Identifier of the user who created the role."},"effectiveEnabled":{"type":"boolean","description":"Indicates whether the role is effectively enabled in the tenant. This reflects the role’s operational state after considering tenant-level configuration or restrictions. Default: true","default":true},"deprecated":{"type":"boolean","description":"Indicates whether the role is deprecated. When set to true, the role is considered deprecated and should not be used for new assignments."},"permissions":{"$ref":"#/components/schemas/RolePermissions"}}},"RolePermissions":{"type":"array","items":{"$ref":"#/components/schemas/RolePermission"}},"RolePermission":{"type":"object","required":["resourceType","actions"],"properties":{"resourceType":{"description":"The type of resource the permission applies to.","$ref":"#/components/schemas/ResourceType"},"actions":{"type":"array","description":"The list of allowed actions for this resource\n- create\n- read\n- update\n- delete\n","items":{"$ref":"#/components/schemas/PermissionAction"}}}},"ResourceType":{"type":"string","description":"Resource type enum for authorization. \n\nNote: The 'apps' resource type is DEPRECATED. Please use 'service-account' instead for managing service accounts.\n","enum":["department","tenant","project","cluster","cluster-config","nodepools","nodes","settings","security-settings","branding-settings","users","apps","service-account","dashboards-overview","dashboards-analytics","dashboards-consumption","roles","access_rules","workloads","workspaces","trainings","inferences","environments","pvc-assets","git-assets","host-path-assets","nfs-assets","s3-assets","compute-resources","templates","credentials","events-history","policies","cm-volume-assets","datavolumes","secret-volume-assets","storage-class-configuration","access-keys","workload-properties","network-topologies","registries","workload-integration-metrics","nodepools-minimal","clusters-minimal"]},"PermissionAction":{"type":"string","enum":["create","read","update","delete"]},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/authorization/roles":{"get":{"summary":"Get a list of roles.","description":"Retrieves a list of all available roles, including both NVIDIA Run:ai predefined roles and custom roles. Use this endpoint to review role configurations, permission sets and permissions.","operationId":"get_roles","tags":["Roles"],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"$ref":"#/components/parameters/SortOrder"},{"$ref":"#/components/parameters/RolesSort"},{"$ref":"#/components/parameters/RolesFilter"},{"$ref":"#/components/parameters/Search"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"type":"object","required":["roles"],"properties":{"roles":{"$ref":"#/components/schemas/Roles"},"next":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Create a role.

> Creates a custom role with the specified permission sets.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Roles","description":"The Roles API allows administrators to define and manage roles within the NVIDIA Run:ai platform. \nA role represents a collection of permission sets that determine what actions can be performed across NVIDIA Run:ai resources.\nNVIDIA Run:ai provides a list of predefined roles that cover common operational needs, such as managing workloads, projects, or data and storage. \nAdministrators can also use this API to create custom roles by combining specific permission sets to match their organization's access model.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"schemas":{"RoleCreationFieldsInternal":{"allOf":[{"$ref":"#/components/schemas/RoleCreationFields"},{"type":"object","required":["name","description"]}]},"RoleCreationFields":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string","description":"The name of the role to create. Must be unique within the given scope.","minLength":1},"description":{"type":"string","description":"A description of the role."},"enabled":{"type":"boolean","default":true,"description":"Specifies whether the role is active. Default: true","nullable":true},"permissionSets":{"type":"array","description":"The permission sets assigned to this role. Each item includes the UUID and name of the permission set.","items":{"$ref":"#/components/schemas/RolePermissionSet"}},"kubernetesPermissions":{"allOf":[{"$ref":"#/components/schemas/KubernetesPermissions"}],"description":"Defines the Kubernetes cluster permissions associated with this role."}}},"RolePermissionSet":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"The universally unique ID (UUID) of the permission set."},"name":{"type":"string","description":"The name of the permission set."}}},"KubernetesPermissions":{"type":"object","properties":{"predefinedRole":{"type":"string","description":"The ID of an NVIDIA Run:ai predefined role. The custom role will include the mapped Kubernetes ClusterRole and its permissions.","nullable":true}}},"Role1":{"allOf":[{"$ref":"#/components/schemas/RoleCreationFields"},{"$ref":"#/components/schemas/RoleCalculatedFields"}]},"RoleCalculatedFields":{"type":"object","required":["id","createdAt","updatedAt","createdBy","custom","effectiveEnabled","permissions"],"properties":{"id":{"type":"integer","format":"int32","description":"The ID of the role."},"createdAt":{"type":"string","description":"The timestamp for when the role was created.","format":"date-time"},"updatedAt":{"type":"string","description":"The timestamp for the last time the role was updated.","format":"date-time"},"createdBy":{"type":"string","description":"Identifier of the user who created the role."},"effectiveEnabled":{"type":"boolean","description":"Indicates whether the role is effectively enabled in the tenant. This reflects the role’s operational state after considering tenant-level configuration or restrictions. Default: true","default":true},"deprecated":{"type":"boolean","description":"Indicates whether the role is deprecated. When set to true, the role is considered deprecated and should not be used for new assignments."},"permissions":{"$ref":"#/components/schemas/RolePermissions"}}},"RolePermissions":{"type":"array","items":{"$ref":"#/components/schemas/RolePermission"}},"RolePermission":{"type":"object","required":["resourceType","actions"],"properties":{"resourceType":{"description":"The type of resource the permission applies to.","$ref":"#/components/schemas/ResourceType"},"actions":{"type":"array","description":"The list of allowed actions for this resource\n- create\n- read\n- update\n- delete\n","items":{"$ref":"#/components/schemas/PermissionAction"}}}},"ResourceType":{"type":"string","description":"Resource type enum for authorization. \n\nNote: The 'apps' resource type is DEPRECATED. Please use 'service-account' instead for managing service accounts.\n","enum":["department","tenant","project","cluster","cluster-config","nodepools","nodes","settings","security-settings","branding-settings","users","apps","service-account","dashboards-overview","dashboards-analytics","dashboards-consumption","roles","access_rules","workloads","workspaces","trainings","inferences","environments","pvc-assets","git-assets","host-path-assets","nfs-assets","s3-assets","compute-resources","templates","credentials","events-history","policies","cm-volume-assets","datavolumes","secret-volume-assets","storage-class-configuration","access-keys","workload-properties","network-topologies","registries","workload-integration-metrics","nodepools-minimal","clusters-minimal"]},"PermissionAction":{"type":"string","enum":["create","read","update","delete"]},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/authorization/roles":{"post":{"summary":"Create a role.","description":"Creates a custom role with the specified permission sets.","operationId":"create_role","tags":["Roles"],"requestBody":{"description":"The role to create.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleCreationFieldsInternal"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Role1"}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Get a role by id.

> Retrieves details for a specific role, including its name, description, scope, and associated permission sets.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Roles","description":"The Roles API allows administrators to define and manage roles within the NVIDIA Run:ai platform. \nA role represents a collection of permission sets that determine what actions can be performed across NVIDIA Run:ai resources.\nNVIDIA Run:ai provides a list of predefined roles that cover common operational needs, such as managing workloads, projects, or data and storage. \nAdministrators can also use this API to create custom roles by combining specific permission sets to match their organization's access model.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"RoleIdPath":{"name":"roleIdPath","in":"path","required":true,"description":"The ID of the role","schema":{"type":"integer","format":"int32","minimum":0}}},"schemas":{"Role1":{"allOf":[{"$ref":"#/components/schemas/RoleCreationFields"},{"$ref":"#/components/schemas/RoleCalculatedFields"}]},"RoleCreationFields":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string","description":"The name of the role to create. Must be unique within the given scope.","minLength":1},"description":{"type":"string","description":"A description of the role."},"enabled":{"type":"boolean","default":true,"description":"Specifies whether the role is active. Default: true","nullable":true},"permissionSets":{"type":"array","description":"The permission sets assigned to this role. Each item includes the UUID and name of the permission set.","items":{"$ref":"#/components/schemas/RolePermissionSet"}},"kubernetesPermissions":{"allOf":[{"$ref":"#/components/schemas/KubernetesPermissions"}],"description":"Defines the Kubernetes cluster permissions associated with this role."}}},"RolePermissionSet":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"The universally unique ID (UUID) of the permission set."},"name":{"type":"string","description":"The name of the permission set."}}},"KubernetesPermissions":{"type":"object","properties":{"predefinedRole":{"type":"string","description":"The ID of an NVIDIA Run:ai predefined role. The custom role will include the mapped Kubernetes ClusterRole and its permissions.","nullable":true}}},"RoleCalculatedFields":{"type":"object","required":["id","createdAt","updatedAt","createdBy","custom","effectiveEnabled","permissions"],"properties":{"id":{"type":"integer","format":"int32","description":"The ID of the role."},"createdAt":{"type":"string","description":"The timestamp for when the role was created.","format":"date-time"},"updatedAt":{"type":"string","description":"The timestamp for the last time the role was updated.","format":"date-time"},"createdBy":{"type":"string","description":"Identifier of the user who created the role."},"effectiveEnabled":{"type":"boolean","description":"Indicates whether the role is effectively enabled in the tenant. This reflects the role’s operational state after considering tenant-level configuration or restrictions. Default: true","default":true},"deprecated":{"type":"boolean","description":"Indicates whether the role is deprecated. When set to true, the role is considered deprecated and should not be used for new assignments."},"permissions":{"$ref":"#/components/schemas/RolePermissions"}}},"RolePermissions":{"type":"array","items":{"$ref":"#/components/schemas/RolePermission"}},"RolePermission":{"type":"object","required":["resourceType","actions"],"properties":{"resourceType":{"description":"The type of resource the permission applies to.","$ref":"#/components/schemas/ResourceType"},"actions":{"type":"array","description":"The list of allowed actions for this resource\n- create\n- read\n- update\n- delete\n","items":{"$ref":"#/components/schemas/PermissionAction"}}}},"ResourceType":{"type":"string","description":"Resource type enum for authorization. \n\nNote: The 'apps' resource type is DEPRECATED. Please use 'service-account' instead for managing service accounts.\n","enum":["department","tenant","project","cluster","cluster-config","nodepools","nodes","settings","security-settings","branding-settings","users","apps","service-account","dashboards-overview","dashboards-analytics","dashboards-consumption","roles","access_rules","workloads","workspaces","trainings","inferences","environments","pvc-assets","git-assets","host-path-assets","nfs-assets","s3-assets","compute-resources","templates","credentials","events-history","policies","cm-volume-assets","datavolumes","secret-volume-assets","storage-class-configuration","access-keys","workload-properties","network-topologies","registries","workload-integration-metrics","nodepools-minimal","clusters-minimal"]},"PermissionAction":{"type":"string","enum":["create","read","update","delete"]},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/authorization/roles/{roleIdPath}":{"get":{"summary":"Get a role by id.","description":"Retrieves details for a specific role, including its name, description, scope, and associated permission sets.","operationId":"get_role","tags":["Roles"],"parameters":[{"$ref":"#/components/parameters/RoleIdPath"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Role1"}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Update a role by id.

> Updates a custom role, including its name, description, or associated permission sets. NVIDIA Run:ai predefined roles cannot be updated.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Roles","description":"The Roles API allows administrators to define and manage roles within the NVIDIA Run:ai platform. \nA role represents a collection of permission sets that determine what actions can be performed across NVIDIA Run:ai resources.\nNVIDIA Run:ai provides a list of predefined roles that cover common operational needs, such as managing workloads, projects, or data and storage. \nAdministrators can also use this API to create custom roles by combining specific permission sets to match their organization's access model.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"RoleIdPath":{"name":"roleIdPath","in":"path","required":true,"description":"The ID of the role","schema":{"type":"integer","format":"int32","minimum":0}}},"schemas":{"RoleCreationFieldsInternal":{"allOf":[{"$ref":"#/components/schemas/RoleCreationFields"},{"type":"object","required":["name","description"]}]},"RoleCreationFields":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string","description":"The name of the role to create. Must be unique within the given scope.","minLength":1},"description":{"type":"string","description":"A description of the role."},"enabled":{"type":"boolean","default":true,"description":"Specifies whether the role is active. Default: true","nullable":true},"permissionSets":{"type":"array","description":"The permission sets assigned to this role. Each item includes the UUID and name of the permission set.","items":{"$ref":"#/components/schemas/RolePermissionSet"}},"kubernetesPermissions":{"allOf":[{"$ref":"#/components/schemas/KubernetesPermissions"}],"description":"Defines the Kubernetes cluster permissions associated with this role."}}},"RolePermissionSet":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"The universally unique ID (UUID) of the permission set."},"name":{"type":"string","description":"The name of the permission set."}}},"KubernetesPermissions":{"type":"object","properties":{"predefinedRole":{"type":"string","description":"The ID of an NVIDIA Run:ai predefined role. The custom role will include the mapped Kubernetes ClusterRole and its permissions.","nullable":true}}},"Role1":{"allOf":[{"$ref":"#/components/schemas/RoleCreationFields"},{"$ref":"#/components/schemas/RoleCalculatedFields"}]},"RoleCalculatedFields":{"type":"object","required":["id","createdAt","updatedAt","createdBy","custom","effectiveEnabled","permissions"],"properties":{"id":{"type":"integer","format":"int32","description":"The ID of the role."},"createdAt":{"type":"string","description":"The timestamp for when the role was created.","format":"date-time"},"updatedAt":{"type":"string","description":"The timestamp for the last time the role was updated.","format":"date-time"},"createdBy":{"type":"string","description":"Identifier of the user who created the role."},"effectiveEnabled":{"type":"boolean","description":"Indicates whether the role is effectively enabled in the tenant. This reflects the role’s operational state after considering tenant-level configuration or restrictions. Default: true","default":true},"deprecated":{"type":"boolean","description":"Indicates whether the role is deprecated. When set to true, the role is considered deprecated and should not be used for new assignments."},"permissions":{"$ref":"#/components/schemas/RolePermissions"}}},"RolePermissions":{"type":"array","items":{"$ref":"#/components/schemas/RolePermission"}},"RolePermission":{"type":"object","required":["resourceType","actions"],"properties":{"resourceType":{"description":"The type of resource the permission applies to.","$ref":"#/components/schemas/ResourceType"},"actions":{"type":"array","description":"The list of allowed actions for this resource\n- create\n- read\n- update\n- delete\n","items":{"$ref":"#/components/schemas/PermissionAction"}}}},"ResourceType":{"type":"string","description":"Resource type enum for authorization. \n\nNote: The 'apps' resource type is DEPRECATED. Please use 'service-account' instead for managing service accounts.\n","enum":["department","tenant","project","cluster","cluster-config","nodepools","nodes","settings","security-settings","branding-settings","users","apps","service-account","dashboards-overview","dashboards-analytics","dashboards-consumption","roles","access_rules","workloads","workspaces","trainings","inferences","environments","pvc-assets","git-assets","host-path-assets","nfs-assets","s3-assets","compute-resources","templates","credentials","events-history","policies","cm-volume-assets","datavolumes","secret-volume-assets","storage-class-configuration","access-keys","workload-properties","network-topologies","registries","workload-integration-metrics","nodepools-minimal","clusters-minimal"]},"PermissionAction":{"type":"string","enum":["create","read","update","delete"]},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/authorization/roles/{roleIdPath}":{"put":{"summary":"Update a role by id.","description":"Updates a custom role, including its name, description, or associated permission sets. NVIDIA Run:ai predefined roles cannot be updated.","operationId":"update_role","tags":["Roles"],"parameters":[{"$ref":"#/components/parameters/RoleIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleCreationFieldsInternal"}}}},"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Role1"}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Delete a role by id.

> Deletes a custom role. Use this endpoint to permanently remove roles that are no longer needed. NVIDIA Run:ai predefined roles cannot be deleted.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Roles","description":"The Roles API allows administrators to define and manage roles within the NVIDIA Run:ai platform. \nA role represents a collection of permission sets that determine what actions can be performed across NVIDIA Run:ai resources.\nNVIDIA Run:ai provides a list of predefined roles that cover common operational needs, such as managing workloads, projects, or data and storage. \nAdministrators can also use this API to create custom roles by combining specific permission sets to match their organization's access model.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"RoleIdPath":{"name":"roleIdPath","in":"path","required":true,"description":"The ID of the role","schema":{"type":"integer","format":"int32","minimum":0}}},"responses":{"204NoContent":{"description":"No Content."},"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}}},"paths":{"/api/v2/authorization/roles/{roleIdPath}":{"delete":{"summary":"Delete a role by id.","description":"Deletes a custom role. Use this endpoint to permanently remove roles that are no longer needed. NVIDIA Run:ai predefined roles cannot be deleted.","operationId":"delete_role","tags":["Roles"],"parameters":[{"$ref":"#/components/parameters/RoleIdPath"}],"responses":{"204":{"$ref":"#/components/responses/204NoContent"},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Enable a role by id.

> Enables a specific role. Disabled roles cannot be assigned to users and do not grant any permissions.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Roles","description":"The Roles API allows administrators to define and manage roles within the NVIDIA Run:ai platform. \nA role represents a collection of permission sets that determine what actions can be performed across NVIDIA Run:ai resources.\nNVIDIA Run:ai provides a list of predefined roles that cover common operational needs, such as managing workloads, projects, or data and storage. \nAdministrators can also use this API to create custom roles by combining specific permission sets to match their organization's access model.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"RoleIdPath":{"name":"roleIdPath","in":"path","required":true,"description":"The ID of the role","schema":{"type":"integer","format":"int32","minimum":0}}},"schemas":{"RoleEnabledDisabledFields":{"type":"object"},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"204NoContent":{"description":"No Content."},"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/authorization/roles/{roleIdPath}/enable":{"post":{"summary":"Enable a role by id.","description":"Enables a specific role. Disabled roles cannot be assigned to users and do not grant any permissions.","operationId":"role_enable","tags":["Roles"],"parameters":[{"$ref":"#/components/parameters/RoleIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleEnabledDisabledFields"}}}},"responses":{"204":{"$ref":"#/components/responses/204NoContent"},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Disable a role by id.

> Disables a specific role. Disabled roles cannot be assigned to users and do not grant any permissions.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Roles","description":"The Roles API allows administrators to define and manage roles within the NVIDIA Run:ai platform. \nA role represents a collection of permission sets that determine what actions can be performed across NVIDIA Run:ai resources.\nNVIDIA Run:ai provides a list of predefined roles that cover common operational needs, such as managing workloads, projects, or data and storage. \nAdministrators can also use this API to create custom roles by combining specific permission sets to match their organization's access model.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"RoleIdPath":{"name":"roleIdPath","in":"path","required":true,"description":"The ID of the role","schema":{"type":"integer","format":"int32","minimum":0}}},"schemas":{"RoleEnabledDisabledFields":{"type":"object"},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"204NoContent":{"description":"No Content."},"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/authorization/roles/{roleIdPath}/disable":{"post":{"summary":"Disable a role by id.","description":"Disables a specific role. Disabled roles cannot be assigned to users and do not grant any permissions.","operationId":"role_disable","tags":["Roles"],"parameters":[{"$ref":"#/components/parameters/RoleIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleEnabledDisabledFields"}}}},"responses":{"204":{"$ref":"#/components/responses/204NoContent"},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```