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.

Deprecated

Get a list of roles.

get

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.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Responses

200

Executed successfully.

application/json

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

/api/v1/authorization/roles

HTTPcURLJavaScriptPython

GET /api/v1/authorization/roles HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": 32,
    "createdAt": "2026-02-04T17:33:29.028Z",
    "updatedAt": "2026-02-04T17:33:29.028Z",
    "deletedAt": "2026-02-04T17:33:29.028Z",
    "createdBy": "[email protected]",
    "custom": true,
    "effectiveEnabled": true,
    "permissions": [
      {
        "resourceType": "department",
        "displayName": "Projects",
        "groupId": "organization",
        "actions": [
          "create"
        ]
      }
    ],
    "name": "admin",
    "description": "can manage all resources",
    "enabled": true,
    "kubernetesPermissions": {
      "predefinedRole": "12"
    }
  }
]

Deprecated

Get a role by id.

get

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.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

roleIdPathinteger · int32Required

The ID of the role

Example: 32

Responses

200

Executed successfully.

application/json

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

/api/v1/authorization/roles/{roleIdPath}

HTTPcURLJavaScriptPython

GET /api/v1/authorization/roles/{roleIdPath} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 32,
  "createdAt": "2026-02-04T17:33:29.028Z",
  "updatedAt": "2026-02-04T17:33:29.028Z",
  "deletedAt": "2026-02-04T17:33:29.028Z",
  "createdBy": "[email protected]",
  "custom": true,
  "effectiveEnabled": true,
  "permissions": [
    {
      "resourceType": "department",
      "displayName": "Projects",
      "groupId": "organization",
      "actions": [
        "create"
      ]
    }
  ],
  "name": "admin",
  "description": "can manage all resources",
  "enabled": true,
  "kubernetesPermissions": {
    "predefinedRole": "12"
  }
}

Get a list of roles.

get

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.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Query parameters

limitinteger · int32 · min: 1 · max: 500Optional

The maximum number of entries to return.

Default: 50

offsetinteger · int32Optional

The offset of the first item returned in the collection.

Example: 100

sortOrderstring · enumOptional

Sort results in descending or ascending order.

Default: ascPossible values:

sortBystring · enumOptional

Sort results by a parameter.

Possible values:

filterBystring[]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 >=.

Example: ["name!=some-access-rule-name","createdAt>=2023-01-01T00:00:00Z"]

searchstringOptional

Filter results by a free text search.

Example: test project

Responses

200

Executed successfully.

application/json

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

/api/v2/authorization/roles

HTTPcURLJavaScriptPython

GET /api/v2/authorization/roles HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "roles": [
    {
      "name": "admin",
      "description": "can manage all resources",
      "enabled": true,
      "permissionSets": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "test"
        }
      ],
      "kubernetesPermissions": {
        "predefinedRole": "12"
      },
      "id": 32,
      "createdAt": "2026-02-04T17:33:29.028Z",
      "updatedAt": "2026-02-04T17:33:29.028Z",
      "createdBy": "[email protected]",
      "effectiveEnabled": true,
      "deprecated": true,
      "permissions": [
        {
          "resourceType": "department",
          "actions": [
            "create"
          ]
        }
      ]
    }
  ],
  "next": 1
}

Create a role.

post

Creates a custom role with the specified permission sets.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Body

application/json

Responses

201

Created

application/json

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

unexpected error

application/json

503

unexpected error

application/json

post

/api/v2/authorization/roles

HTTPcURLJavaScriptPython

POST /api/v2/authorization/roles HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 199

{
  "name": "admin",
  "description": "can manage all resources",
  "enabled": true,
  "permissionSets": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "test"
    }
  ],
  "kubernetesPermissions": {
    "predefinedRole": "12"
  }
}

{
  "name": "admin",
  "description": "can manage all resources",
  "enabled": true,
  "permissionSets": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "test"
    }
  ],
  "kubernetesPermissions": {
    "predefinedRole": "12"
  },
  "id": 32,
  "createdAt": "2026-02-04T17:33:29.028Z",
  "updatedAt": "2026-02-04T17:33:29.028Z",
  "createdBy": "[email protected]",
  "effectiveEnabled": true,
  "deprecated": true,
  "permissions": [
    {
      "resourceType": "department",
      "actions": [
        "create"
      ]
    }
  ]
}

Get a role by id.

get

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

roleIdPathinteger · int32Required

The ID of the role

Example: 32

Responses

200

Executed successfully.

application/json

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

/api/v2/authorization/roles/{roleIdPath}

HTTPcURLJavaScriptPython

GET /api/v2/authorization/roles/{roleIdPath} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "admin",
  "description": "can manage all resources",
  "enabled": true,
  "permissionSets": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "test"
    }
  ],
  "kubernetesPermissions": {
    "predefinedRole": "12"
  },
  "id": 32,
  "createdAt": "2026-02-04T17:33:29.028Z",
  "updatedAt": "2026-02-04T17:33:29.028Z",
  "createdBy": "[email protected]",
  "effectiveEnabled": true,
  "deprecated": true,
  "permissions": [
    {
      "resourceType": "department",
      "actions": [
        "create"
      ]
    }
  ]
}

Update a role by id.

put

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

roleIdPathinteger · int32Required

The ID of the role

Example: 32

Body

application/json

Responses

200

Executed successfully.

application/json

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

put

/api/v2/authorization/roles/{roleIdPath}

HTTPcURLJavaScriptPython

PUT /api/v2/authorization/roles/{roleIdPath} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 199

{
  "name": "admin",
  "description": "can manage all resources",
  "enabled": true,
  "permissionSets": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "test"
    }
  ],
  "kubernetesPermissions": {
    "predefinedRole": "12"
  }
}

{
  "name": "admin",
  "description": "can manage all resources",
  "enabled": true,
  "permissionSets": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "test"
    }
  ],
  "kubernetesPermissions": {
    "predefinedRole": "12"
  },
  "id": 32,
  "createdAt": "2026-02-04T17:33:29.028Z",
  "updatedAt": "2026-02-04T17:33:29.028Z",
  "createdBy": "[email protected]",
  "effectiveEnabled": true,
  "deprecated": true,
  "permissions": [
    {
      "resourceType": "department",
      "actions": [
        "create"
      ]
    }
  ]
}

Delete a role by id.

delete

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

roleIdPathinteger · int32Required

The ID of the role

Example: 32

Responses

204

No Content.

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

delete

/api/v2/authorization/roles/{roleIdPath}

HTTPcURLJavaScriptPython

DELETE /api/v2/authorization/roles/{roleIdPath} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Enable a role by id.

post

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

roleIdPathinteger · int32Required

The ID of the role

Example: 32

Body

application/json

objectOptional

Responses

204

No Content.

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

post

/api/v2/authorization/roles/{roleIdPath}/enable

HTTPcURLJavaScriptPython

POST /api/v2/authorization/roles/{roleIdPath}/enable HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

No content

Disable a role by id.

post

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

roleIdPathinteger · int32Required

The ID of the role

Example: 32

Body

application/json

objectOptional

Responses

204

No Content.

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

post

/api/v2/authorization/roles/{roleIdPath}/disable

HTTPcURLJavaScriptPython

POST /api/v2/authorization/roles/{roleIdPath}/disable HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

No content