Access rules

Access rules provide user authorization to system resources and entities. It is managed using Role-based access control (RBAC) which is a policy-neutral access control mechanism defined around roles and privileges. The components of RBAC make it simple to manage access to system resources and entities. For more information, see Access control.

List the access rules.

get

Retrieve a list of access rules.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Query parameters

subjectTypestringOptional

The type of resource we want to filter by.

Example: user

subjectIdFilterstringOptionalDeprecated

Part of the subject id that we want to filter by.

Example: some.user

subjectIdsstring[]Optional

The ids of the subjects to filter the response for.

Example: [email protected]

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

lastUpdatedstringOptional

Filter by last update time.

Example: 2021-12-14T16:04:15.099Z

includeDeletedbooleanOptional

True to include deleted objects in the result.

Default: falseExample: false

clusterIdstring · uuidOptional

Filter using the Universally Unique Identifier (UUID) of the cluster.

Example: d73a738f-fab3-430a-8fa3-5241493d7128

scopeTypestringOptionalDeprecated

The type of resource we want to filter by.

Example: project

scopeIdstringOptional

The scope resource id that we want to filter by.

Example: 2

roleIdinteger · int32 · min: 1OptionalDeprecated

The role id we want to filter by.

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

401

Unauthorized

application/json

403

Forbidden

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

/api/v1/authorization/access-rules

HTTPcURLJavaScriptPython

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

{
  "totalRecords": 1,
  "displayRecords": 1,
  "accessRules": [
    {
      "subjectId": "[email protected]",
      "subjectType": null,
      "roleId": 53142648,
      "scopeId": "a418ed33-9399-48c0-a890-122cadd13bfd",
      "scopeType": null,
      "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
      "roleName": "admin",
      "scopeName": "tenant-x",
      "id": 32,
      "createdAt": "2026-02-05T00:14:01.424Z",
      "updatedAt": "2026-02-05T00:14:01.424Z",
      "deletedAt": "2026-02-05T00:14:01.424Z",
      "tenantId": 1001,
      "createdBy": "[email protected]",
      "status": {
        "phase": "Ready",
        "message": "Failed to enforce department 'department-a'",
        "details": "NotReady: [cluster1-uuid]; Ready: [cluster2-uuid, cluster3-uuid]"
      }
    }
  ]
}

Create an access rule.

post

Use to bind a predefined role to a subject (user, group or application) in a scope.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Body

application/json

subjectIdstringRequired

The unique identifier of the subject (e.g., user, group, or app).

Example: [email protected]

subjectTypeall ofRequired

string · enumOptional

Subject type enum for access rules.

Note: The 'app' subject type is DEPRECATED. Please use 'service-account' instead for service accounts.

Possible values:

and

anyOptional

The subject assigned to the access rule. Valid values: user, group, app.

roleIdinteger · int32Required

The numeric ID of the assigned role.

Example: 53142648

scopeIdstringRequired

The unique identifier of the scope.

Example: a418ed33-9399-48c0-a890-122cadd13bfd

scopeTypeall ofRequired

string · enumOptionalPossible values:

and

anyOptional

The type of scope the access rule applies to. Valid values: system, tenant, cluster, department, project.

clusterIdstring · uuidOptional

The id of the cluster.

Example: 71f69d83-ba66-4822-adf5-55ce55efd210

Responses

201

Created

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

post

/api/v1/authorization/access-rules

HTTPcURLJavaScriptPython

POST /api/v1/authorization/access-rules HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 181

{
  "subjectId": "[email protected]",
  "subjectType": null,
  "roleId": 53142648,
  "scopeId": "a418ed33-9399-48c0-a890-122cadd13bfd",
  "scopeType": null,
  "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210"
}

{
  "subjectId": "[email protected]",
  "subjectType": null,
  "roleId": 53142648,
  "scopeId": "a418ed33-9399-48c0-a890-122cadd13bfd",
  "scopeType": null,
  "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
  "roleName": "admin",
  "scopeName": "tenant-x",
  "id": 32,
  "createdAt": "2026-02-05T00:14:01.424Z",
  "updatedAt": "2026-02-05T00:14:01.424Z",
  "deletedAt": "2026-02-05T00:14:01.424Z",
  "tenantId": 1001,
  "createdBy": "[email protected]",
  "status": {
    "phase": "Ready",
    "message": "Failed to enforce department 'department-a'",
    "details": "NotReady: [cluster1-uuid]; Ready: [cluster2-uuid, cluster3-uuid]"
  }
}

Get an access rule.

get

Use to retrieve the details of an access rule by id.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

accessRuleIdinteger · int32Required

The id of the access rule to retrieve

Example: 32

Responses

200

Executed successfully.

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/access-rules/{accessRuleId}

HTTPcURLJavaScriptPython

GET /api/v1/authorization/access-rules/{accessRuleId} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "subjectId": "[email protected]",
  "subjectType": null,
  "roleId": 53142648,
  "scopeId": "a418ed33-9399-48c0-a890-122cadd13bfd",
  "scopeType": null,
  "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
  "roleName": "admin",
  "scopeName": "tenant-x",
  "id": 32,
  "createdAt": "2026-02-05T00:14:01.424Z",
  "updatedAt": "2026-02-05T00:14:01.424Z",
  "deletedAt": "2026-02-05T00:14:01.424Z",
  "tenantId": 1001,
  "createdBy": "[email protected]",
  "status": {
    "phase": "Ready",
    "message": "Failed to enforce department 'department-a'",
    "details": "NotReady: [cluster1-uuid]; Ready: [cluster2-uuid, cluster3-uuid]"
  },
  "scopePath": "runai/production-cluster/dep-42/prj-73"
}

Delete an access rule.

delete

Use to delete the subject permissions assigned by access rule id.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

accessRuleIdinteger · int32Required

The id of the access rule to retrieve

Example: 32

Responses

204

No Content.

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/v1/authorization/access-rules/{accessRuleId}

HTTPcURLJavaScriptPython

DELETE /api/v1/authorization/access-rules/{accessRuleId} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Count access rules.

get

Use to retrieve the number of access rules.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Query parameters

includeDeletedbooleanOptional

True to include deleted objects in the result.

Default: falseExample: false

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/v1/authorization/access-rules/count

HTTPcURLJavaScriptPython

GET /api/v1/authorization/access-rules/count HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 1
}

Delete Multiple Access Rules

post

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Body

application/json

Deletes a batch of access rules in a single operation. It requires a list of rule IDs and an action flag explicitly set to "delete". It returns the result of the operation, including which items were successfully deleted and which failed.

idsstring · uuid[] · min: 1Required

List of ids to perform the action on.

actionstring · enumRequired

Specifies the operation to perform. Must be set to "delete".

Possible values:

Responses

200

Request completed 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

post

/api/v1/authorization/access-rules/batch

HTTPcURLJavaScriptPython

POST /api/v1/authorization/access-rules/batch HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 66

{
  "ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "action": "delete"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "succeeded": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "failed": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "code": 1,
      "message": "text"
    }
  ]
}

Create Multiple Access Rules

post

Creates a batch of access rules in a single operation. Requires a list of access rule objects, each specifying the subject, role, and scope. Returns the result of the operation, including which rules were successfully created and any that failed, along with error messages if applicable.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Body

application/json

Responses

200

Request completed 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

post

/api/v1/authorization/access-rules/batch-create

HTTPcURLJavaScriptPython

POST /api/v1/authorization/access-rules/batch-create HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 189

{
  "payload": {
    "roleId": 53142648,
    "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
    "subjects": [
      {
        "subjectId": "[email protected]",
        "subjectType": null
      }
    ],
    "scopes": [
      {
        "scopeId": "text",
        "scopeType": null
      }
    ]
  }
}

{
  "succeeded": [
    {
      "subjectId": "[email protected]",
      "subjectType": null,
      "roleId": 53142648,
      "scopeId": "a418ed33-9399-48c0-a890-122cadd13bfd",
      "scopeType": null,
      "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
      "roleName": "admin",
      "scopeName": "tenant-x",
      "id": 32,
      "createdAt": "2026-02-05T00:14:01.424Z",
      "updatedAt": "2026-02-05T00:14:01.424Z",
      "deletedAt": "2026-02-05T00:14:01.424Z",
      "tenantId": 1001,
      "createdBy": "[email protected]",
      "status": {
        "phase": "Ready",
        "message": "Failed to enforce department 'department-a'",
        "details": "NotReady: [cluster1-uuid]; Ready: [cluster2-uuid, cluster3-uuid]"
      }
    }
  ],
  "failed": []
}