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

AuthorizationstringRequired

Bearer authentication

Responses

200

Executed successfully.

application/json

idinteger · int32RequiredExample: 32

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

deletedAtstring · date-time · nullableOptional

createdBystringRequiredExample: [email protected]

custombooleanRequired

effectiveEnabledbooleanRequiredDefault: true

namestringRequiredExample: admin

descriptionstringRequiredExample: can manage all resources

enabledboolean · nullableOptionalDefault: true

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

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

[
  {
    "id": 32,
    "createdAt": "2026-03-20T13:52:22.082Z",
    "updatedAt": "2026-03-20T13:52:22.082Z",
    "deletedAt": "2026-03-20T13:52:22.082Z",
    "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

AuthorizationstringRequired

Bearer authentication

Path parameters

roleIdPathinteger · int32Required

The ID of the role

Example: 32

Responses

200

Executed successfully.

application/json

idinteger · int32RequiredExample: 32

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

deletedAtstring · date-time · nullableOptional

createdBystringRequiredExample: [email protected]

custombooleanRequired

effectiveEnabledbooleanRequiredDefault: true

namestringRequiredExample: admin

descriptionstringRequiredExample: can manage all resources

enabledboolean · nullableOptionalDefault: true

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}

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

{
  "id": 32,
  "createdAt": "2026-03-20T13:52:22.082Z",
  "updatedAt": "2026-03-20T13:52:22.082Z",
  "deletedAt": "2026-03-20T13:52:22.082Z",
  "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

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

nextintegerOptionalExample: 1

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

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-03-20T13:52:22.082Z",
      "updatedAt": "2026-03-20T13:52:22.082Z",
      "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

AuthorizationstringRequired

Bearer authentication

Body

namestring · min: 1Required

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

Example: admin

descriptionstringRequired

A description of the role.

Example: can manage all resources

enabledboolean · nullableOptional

Specifies whether the role is active. Default: true

Default: true

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

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-03-20T13:52:22.082Z",
  "updatedAt": "2026-03-20T13:52:22.082Z",
  "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

AuthorizationstringRequired

Bearer authentication

Path parameters

roleIdPathinteger · int32Required

The ID of the role

Example: 32

Responses

200

Executed successfully.

application/json

namestring · min: 1Required

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

Example: admin

descriptionstringRequired

A description of the role.

Example: can manage all resources

enabledboolean · nullableOptional

Specifies whether the role is active. Default: true

Default: true

idinteger · int32Required

The ID of the role.

Example: 32

createdAtstring · date-timeRequired

The timestamp for when the role was created.

updatedAtstring · date-timeRequired

The timestamp for the last time the role was updated.

createdBystringRequired

Identifier of the user who created the role.

Example: [email protected]

effectiveEnabledbooleanRequired

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

deprecatedbooleanOptional

Indicates whether the role is deprecated. When set to true, the role is considered deprecated and should not be used for new assignments.

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}

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-03-20T13:52:22.082Z",
  "updatedAt": "2026-03-20T13:52:22.082Z",
  "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

AuthorizationstringRequired

Bearer authentication

Path parameters

roleIdPathinteger · int32Required

The ID of the role

Example: 32

Body

namestring · min: 1Required

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

Example: admin

descriptionstringRequired

A description of the role.

Example: can manage all resources

enabledboolean · nullableOptional

Specifies whether the role is active. Default: true

Default: true

Responses

200

Executed successfully.

application/json

namestring · min: 1Required

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

Example: admin

descriptionstringRequired

A description of the role.

Example: can manage all resources

enabledboolean · nullableOptional

Specifies whether the role is active. Default: true

Default: true

idinteger · int32Required

The ID of the role.

Example: 32

createdAtstring · date-timeRequired

The timestamp for when the role was created.

updatedAtstring · date-timeRequired

The timestamp for the last time the role was updated.

createdBystringRequired

Identifier of the user who created the role.

Example: [email protected]

effectiveEnabledbooleanRequired

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

deprecatedbooleanOptional

Indicates whether the role is deprecated. When set to true, the role is considered deprecated and should not be used for new assignments.

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}

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-03-20T13:52:22.082Z",
  "updatedAt": "2026-03-20T13:52:22.082Z",
  "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

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}

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

AuthorizationstringRequired

Bearer authentication

Path parameters

roleIdPathinteger · int32Required

The ID of the role

Example: 32

Body

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

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

AuthorizationstringRequired

Bearer authentication

Path parameters

roleIdPathinteger · int32Required

The ID of the role

Example: 32

Body

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

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

PreviousService Accounts NextTokens

Last updated 11 days ago

Good afternoon

hashtagGet a list of roles.

hashtagGet a role by id.

hashtagGet a list of roles.

hashtagCreate a role.

hashtagGet a role by id.

hashtagUpdate a role by id.

hashtagDelete a role by id.

hashtagEnable a role by id.

hashtagDisable a role by id.

Get a list of roles.

Get a role by id.

Get a list of roles.

Create a role.

Get a role by id.

Update a role by id.

Delete a role by id.

Enable a role by id.

Disable a role by id.