NVIDIA Run:ai

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.Deprecated

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.

SecuritybearerAuth
Responses
200

Executed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

500

unexpected error

503

unexpected error

get/api/v1/authorization/roles
Response samples
application/json
[
  • {
    }
]

Get a role by id.Deprecated

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.

SecuritybearerAuth
Request
path Parameters
roleIdPath
required
integer <int32> >= 0

The ID of the role

Example: 32
Responses
200

Executed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

get/api/v1/authorization/roles/{roleIdPath}
Response samples
application/json
{
  • "id": 32,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "user@run.ai",
  • "custom": true,
  • "effectiveEnabled": true,
  • "permissions": [
    ],
  • "name": "admin",
  • "description": "can manage all resources",
  • "enabled": true,
  • "kubernetesPermissions": {
    }
}

Create a role.

Creates a custom role with the specified permission sets.

SecuritybearerAuth
Request
Request Body schema: application/json
required

The role to create.

name
required
string non-empty

The name of the role to create. Must be unique within the given scope.

description
required
string

A description of the role.

enabled
boolean or null
Default: true

Specifies whether the role is active. Default: true

Array of objects (RolePermissionSet)

The permission sets assigned to this role. Each item includes the UUID and name of the permission set.

object

Defines the Kubernetes cluster permissions associated with this role.

Responses
201

Created

400

Bad request.

401

Unauthorized

403

Forbidden

500

unexpected error

503

unexpected error

post/api/v2/authorization/roles
Request samples
application/json
{
  • "name": "admin",
  • "description": "can manage all resources",
  • "enabled": true,
  • "permissionSets": [
    ],
  • "kubernetesPermissions": {
    }
}
Response samples
application/json
{
  • "name": "admin",
  • "description": "can manage all resources",
  • "enabled": true,
  • "permissionSets": [
    ],
  • "kubernetesPermissions": {
    },
  • "id": 32,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "user@run.ai",
  • "effectiveEnabled": true,
  • "deprecated": true,
  • "permissions": [
    ]
}

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.

SecuritybearerAuth
Request
query Parameters
limit
integer <int32> [ 1 .. 500 ]
Default: 50

The maximum number of entries to return.

offset
integer <int32>

The offset of the first item returned in the collection.

Example: offset=100
sortOrder
string
Default: "asc"

Sort results in descending or ascending order.

Enum: "asc" "desc"
sortBy
string (RolesSortFilterFields)

Sort results by a parameter.

Enum: "name" "createdAt" "createdBy" "custom" "scopeType" "enabled"
filterBy
Array of strings

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 >=.

Example: filterBy=name!=some-access-rule-name,createdAt>=2023-01-01T00:00:00Z
search
string

Filter results by a free text search.

Example: search=test project
Responses
200

Executed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

500

unexpected error

503

unexpected error

get/api/v2/authorization/roles
Response samples
application/json
{
  • "roles": [
    ],
  • "next": 1
}

Get a role by id.

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

SecuritybearerAuth
Request
path Parameters
roleIdPath
required
integer <int32> >= 0

The ID of the role

Example: 32
Responses
200

Executed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

get/api/v2/authorization/roles/{roleIdPath}
Response samples
application/json
{
  • "name": "admin",
  • "description": "can manage all resources",
  • "enabled": true,
  • "permissionSets": [
    ],
  • "kubernetesPermissions": {
    },
  • "id": 32,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "user@run.ai",
  • "effectiveEnabled": true,
  • "deprecated": true,
  • "permissions": [
    ]
}

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.

SecuritybearerAuth
Request
path Parameters
roleIdPath
required
integer <int32> >= 0

The ID of the role

Example: 32
Responses
204

No Content.

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

delete/api/v2/authorization/roles/{roleIdPath}
Response samples
application/json
{
  • "code": 400,
  • "message": "Required parameter is missing"
}

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.

SecuritybearerAuth
Request
path Parameters
roleIdPath
required
integer <int32> >= 0

The ID of the role

Example: 32
Request Body schema: application/json
required
name
required
string non-empty

The name of the role to create. Must be unique within the given scope.

description
required
string

A description of the role.

enabled
boolean or null
Default: true

Specifies whether the role is active. Default: true

Array of objects (RolePermissionSet)

The permission sets assigned to this role. Each item includes the UUID and name of the permission set.

object

Defines the Kubernetes cluster permissions associated with this role.

Responses
200

Executed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

put/api/v2/authorization/roles/{roleIdPath}
Request samples
application/json
{
  • "name": "admin",
  • "description": "can manage all resources",
  • "enabled": true,
  • "permissionSets": [
    ],
  • "kubernetesPermissions": {
    }
}
Response samples
application/json
{
  • "name": "admin",
  • "description": "can manage all resources",
  • "enabled": true,
  • "permissionSets": [
    ],
  • "kubernetesPermissions": {
    },
  • "id": 32,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "user@run.ai",
  • "effectiveEnabled": true,
  • "deprecated": true,
  • "permissions": [
    ]
}

Enable a role by id.

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

SecuritybearerAuth
Request
path Parameters
roleIdPath
required
integer <int32> >= 0

The ID of the role

Example: 32
Request Body schema: application/json
required
object (RoleEnabledDisabledFields)
Responses
204

No Content.

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

post/api/v2/authorization/roles/{roleIdPath}/enable
Request samples
application/json
{ }
Response samples
application/json
{
  • "code": 400,
  • "message": "Required parameter is missing"
}

Disable a role by id.

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

SecuritybearerAuth
Request
path Parameters
roleIdPath
required
integer <int32> >= 0

The ID of the role

Example: 32
Request Body schema: application/json
required
object (RoleEnabledDisabledFields)
Responses
204

No Content.

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

post/api/v2/authorization/roles/{roleIdPath}/disable
Request samples
application/json
{ }
Response samples
application/json
{
  • "code": 400,
  • "message": "Required parameter is missing"
}
➔ Next to Tokens