# Roles

A role is a group of permissions that can be granted. Permissions are a set of actions that can be applied to entities. For more information, see [Roles](https://run-ai-docs.nvidia.com/self-hosted/infrastructure-setup/authentication/roles).

## Get a list of roles.

> Use to retrieve a list of roles.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.22"},"tags":[{"name":"Roles","description":"A role is a group of permissions that can be granted. \nPermissions are a set of actions that can be applied to entities.\nFor more information, see [Roles](https://run-ai-docs.nvidia.com/self-hosted/infrastructure-setup/authentication/roles).\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"schemas":{"Roles":{"type":"array","items":{"$ref":"#/components/schemas/Role1"}},"Role1":{"allOf":[{"$ref":"#/components/schemas/RoleCreationFields"},{"$ref":"#/components/schemas/RoleCalculatedFields"}]},"RoleCreationFields":{"type":"object","required":["name","description","permissions"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"permissions":{"$ref":"#/components/schemas/Permissions"},"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","enum":["department","tenant","project","cluster","cluster-config","nodepools","nodes","settings","security-settings","users","groups","apps","dashboards-overview","dashboards-analytics","dashboards-consumption","roles","access_rules","jobs","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","user-apps","workload-properties"]},"ResourceTypeGroupId":{"type":"string","enum":["organization","physical-resource","iam","dashboard","workload","workload-asset"]},"Action":{"type":"string","enum":["create","read","update","delete","sync"]},"KubernetesPermissions":{"type":"object","description":"This object indicate what kubernetes cluster permission should this role should get","properties":{"predefinedRole":{"type":"string","description":"An id of a predefined role to copy the cluster permissions from","nullable":true}}},"RoleCalculatedFields":{"type":"object","required":["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}}},"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.","operationId":"get_roles_v1","tags":["Roles"],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Roles"}}}},"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.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.22"},"tags":[{"name":"Roles","description":"A role is a group of permissions that can be granted. \nPermissions are a set of actions that can be applied to entities.\nFor more information, see [Roles](https://run-ai-docs.nvidia.com/self-hosted/infrastructure-setup/authentication/roles).\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 to retrieve","schema":{"type":"integer","format":"int32","minimum":0}}},"schemas":{"Role1":{"allOf":[{"$ref":"#/components/schemas/RoleCreationFields"},{"$ref":"#/components/schemas/RoleCalculatedFields"}]},"RoleCreationFields":{"type":"object","required":["name","description","permissions"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"permissions":{"$ref":"#/components/schemas/Permissions"},"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","enum":["department","tenant","project","cluster","cluster-config","nodepools","nodes","settings","security-settings","users","groups","apps","dashboards-overview","dashboards-analytics","dashboards-consumption","roles","access_rules","jobs","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","user-apps","workload-properties"]},"ResourceTypeGroupId":{"type":"string","enum":["organization","physical-resource","iam","dashboard","workload","workload-asset"]},"Action":{"type":"string","enum":["create","read","update","delete","sync"]},"KubernetesPermissions":{"type":"object","description":"This object indicate what kubernetes cluster permission should this role should get","properties":{"predefinedRole":{"type":"string","description":"An id of a predefined role to copy the cluster permissions from","nullable":true}}},"RoleCalculatedFields":{"type":"object","required":["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}}},"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.","operationId":"get_role_v1","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"}}}}}}
```