Ctrlk
Contact support
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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: user@run.ai
custombooleanRequired
effectiveEnabledbooleanRequiredDefault: true
namestringRequiredExample: admin
descriptionstringRequiredExample: can manage all resources
enabledboolean · nullableOptionalDefault: true
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-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "deletedAt": "2026-01-01T00:00:00.000Z",
    "createdBy": "user@run.ai",
    "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: user@run.ai
custombooleanRequired
effectiveEnabledbooleanRequiredDefault: true
namestringRequiredExample: admin
descriptionstringRequiredExample: can manage all resources
enabledboolean · nullableOptionalDefault: true
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-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "deletedAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "user@run.ai",
  "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
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",
      "scopeType": "tenant",
      "scopeId": "text",
      "enabled": true,
      "permissionSets": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "test"
        }
      ],
      "kubernetesPermissions": {
        "predefinedRole": "12"
      },
      "id": 32,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "createdBy": "user@run.ai",
      "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
scopeTypestring · enumOptional

The type of scope where the role applies. Valid values: system, tenant

Default: tenantPossible values:
scopeIdstring · nullableOptional

The ID of the scope where this role is defined.

enabledboolean · nullableOptional

Specifies whether the role is active. Default: true

Default: true
Responses
201

Created

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
scopeTypestring · enumOptional

The type of scope where the role applies. Valid values: system, tenant

Default: tenantPossible values:
scopeIdstring · nullableOptional

The ID of the scope where this role is defined.

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: user@run.ai
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.

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: 237

{
  "name": "admin",
  "description": "can manage all resources",
  "scopeType": "tenant",
  "scopeId": "text",
  "enabled": true,
  "permissionSets": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "test"
    }
  ],
  "kubernetesPermissions": {
    "predefinedRole": "12"
  }
}
{
  "name": "admin",
  "description": "can manage all resources",
  "scopeType": "tenant",
  "scopeId": "text",
  "enabled": true,
  "permissionSets": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "test"
    }
  ],
  "kubernetesPermissions": {
    "predefinedRole": "12"
  },
  "id": 32,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "user@run.ai",
  "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
scopeTypestring · enumOptional

The type of scope where the role applies. Valid values: system, tenant

Default: tenantPossible values:
scopeIdstring · nullableOptional

The ID of the scope where this role is defined.

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: user@run.ai
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.

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",
  "scopeType": "tenant",
  "scopeId": "text",
  "enabled": true,
  "permissionSets": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "test"
    }
  ],
  "kubernetesPermissions": {
    "predefinedRole": "12"
  },
  "id": 32,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "user@run.ai",
  "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
scopeTypestring · enumOptional

The type of scope where the role applies. Valid values: system, tenant

Default: tenantPossible values:
scopeIdstring · nullableOptional

The ID of the scope where this role is defined.

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
scopeTypestring · enumOptional

The type of scope where the role applies. Valid values: system, tenant

Default: tenantPossible values:
scopeIdstring · nullableOptional

The ID of the scope where this role is defined.

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: user@run.ai
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.

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: 237

{
  "name": "admin",
  "description": "can manage all resources",
  "scopeType": "tenant",
  "scopeId": "text",
  "enabled": true,
  "permissionSets": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "test"
    }
  ],
  "kubernetesPermissions": {
    "predefinedRole": "12"
  }
}
{
  "name": "admin",
  "description": "can manage all resources",
  "scopeType": "tenant",
  "scopeId": "text",
  "enabled": true,
  "permissionSets": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "test"
    }
  ],
  "kubernetesPermissions": {
    "predefinedRole": "12"
  },
  "id": 32,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "user@run.ai",
  "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.

No content
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
scopeTypestring · enumOptionalDefault: tenantPossible values:
Responses
204

No Content.

No content
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: 22

{
  "scopeType": "tenant"
}
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
scopeTypestring · enumOptionalDefault: tenantPossible values:
Responses
204

No Content.

No content
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: 22

{
  "scopeType": "tenant"
}
No content
PreviousService Accounts
NextTokens

Last updated