> This page is for Self-Hosted, version v3.0 (default). > For other versions, use one of these documentation indexes: > - v3.0 (default): https://docs.nvidia.com/run-ai/self-hosted/v3.0/llms.txt > - v2.26: https://docs.nvidia.com/run-ai/self-hosted/v2.26/llms.txt > - v2.25: https://docs.nvidia.com/run-ai/self-hosted/v2.25/llms.txt > - v2.24: https://docs.nvidia.com/run-ai/self-hosted/v2.24/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/run-ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/run-ai/_mcp/server. # Get a list of roles. GET http://localhost:8080/api/v2/authorization/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. Reference: https://docs.nvidia.com/run-ai/self-hosted/reference/rest-api/endpoints/authentication-and-authorization/roles/get-roles ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication ## Request ### Query parameters - `limit` (integer, optional, default: 50) — The maximum number of entries to return. - `offset` (integer, optional) — The offset of the first item returned in the collection. - `sortOrder` (enum, optional, default: asc) — Sort results in descending or ascending order. - Allowed values: `asc`, `desc` - `sortBy` (enum, optional) — Sort results by a parameter. - Allowed values: `name`, `createdAt`, `createdBy`, `custom`, `scopeType`, `enabled` - `filterBy` (list of string, optional) — 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 >=. - `search` (string, optional) — Filter results by a free text search. ## Response ### 200 Executed successfully. - `roles` (list of Role, required) - `next` (integer, optional) ## Errors ### 400 Bad Request Error Bad request. - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 401 Unauthorized Error Unauthorized - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 403 Forbidden Error Forbidden - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 500 Internal Server Error unexpected error - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 503 Service Unavailable Error unexpected error - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ## Types ### Role - `name` (string, required) — The name of the role to create. Must be unique within the given scope. - `description` (string, required) — A description of the role. - `id` (integer, required) — The ID of the role. - `createdAt` (datetime, required) — The timestamp for when the role was created. - `updatedAt` (datetime, required) — The timestamp for the last time the role was updated. - `createdBy` (string, required) — Identifier of the user who created the role. - `effectiveEnabled` (boolean, required, default: true) — 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 - `permissions` (list of RolePermission, required) - `enabled` (boolean, optional, nullable, default: true) — Specifies whether the role is active. Default: true - `permissionSets` (list of RolePermissionSet, optional) — The permission sets assigned to this role. Each item includes the UUID and name of the permission set. - `kubernetesPermissions` (KubernetesPermissions, optional) — Defines the Kubernetes cluster permissions associated with this role. - `deprecated` (boolean, optional) — Indicates whether the role is deprecated. When set to true, the role is considered deprecated and should not be used for new assignments. ### RolePermission - `resourceType` (enum, required) — The type of resource the permission applies to. - Allowed values: `department`, `tenant`, `project`, `cluster`, `cluster-config`, `nodepools`, `nodes`, `settings`, `security-settings`, `notification-settings`, `branding-settings`, `users`, `apps`, `service-account`, `roles`, `access_rules`, `workloads`, `applications`, `workspaces`, `trainings`, `inferences`, `environments`, `pvc-assets`, `git-assets`, `host-path-assets`, `nfs-assets`, `s3-assets`, `compute-resources`, `resource-claim-templates`, `templates`, `credentials`, `events-history`, `policies`, `cm-volume-assets`, `datavolumes`, `secret-volume-assets`, `storage-class-configuration`, `device-classes`, `access-keys`, `workload-properties`, `network-topologies`, `registries`, `workload-integration-metrics`, `nodepools-minimal`, `clusters-minimal`, `users-minimal` - `actions` (list of enum, required) — The list of allowed actions for this resource - create - read - update - delete - Allowed values: `create`, `read`, `update`, `delete` ### RolePermissionSet - `id` (string, required) — The universally unique ID (UUID) of the permission set. - `name` (string, optional) — The name of the permission set. ### KubernetesPermissions - `predefinedRole` (string, optional, nullable) — The ID of an NVIDIA Run:ai predefined role. The custom role will include the mapped Kubernetes ClusterRole and its permissions. ## Examples **Response** ```json { "roles": [ { "name": "admin", "description": "can manage all resources", "id": 32, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z", "createdBy": "user@run.ai", "effectiveEnabled": true, "permissions": [ { "resourceType": "department", "actions": [ "create" ] } ], "enabled": true, "permissionSets": [ { "id": "string", "name": "test" } ], "kubernetesPermissions": { "predefinedRole": "12" }, "deprecated": true } ], "next": 1 } ``` **SDK Code** ```python import requests url = "http://localhost:8080/api/v2/authorization/roles" querystring = {"filterBy":"name!=some-access-rule-name,createdAt>=2023-01-01T00:00:00Z"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'http://localhost:8080/api/v2/authorization/roles?filterBy=name%21%3Dsome-access-rule-name%2CcreatedAt%3E%3D2023-01-01T00%3A00%3A00Z'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "http://localhost:8080/api/v2/authorization/roles?filterBy=name%21%3Dsome-access-rule-name%2CcreatedAt%3E%3D2023-01-01T00%3A00%3A00Z" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("http://localhost:8080/api/v2/authorization/roles?filterBy=name%21%3Dsome-access-rule-name%2CcreatedAt%3E%3D2023-01-01T00%3A00%3A00Z") http = Net::HTTP.new(url.host, url.port) request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("http://localhost:8080/api/v2/authorization/roles?filterBy=name%21%3Dsome-access-rule-name%2CcreatedAt%3E%3D2023-01-01T00%3A00%3A00Z") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'http://localhost:8080/api/v2/authorization/roles?filterBy=name%21%3Dsome-access-rule-name%2CcreatedAt%3E%3D2023-01-01T00%3A00%3A00Z', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("http://localhost:8080/api/v2/authorization/roles?filterBy=name%21%3Dsome-access-rule-name%2CcreatedAt%3E%3D2023-01-01T00%3A00%3A00Z"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "http://localhost:8080/api/v2/authorization/roles?filterBy=name%21%3Dsome-access-rule-name%2CcreatedAt%3E%3D2023-01-01T00%3A00%3A00Z")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```