Roles

Overview

The Confident AI SDK exposes every Role method on the platform. This page documents how to call these methods in all supported languages. See the introduction to install the SDK and set your API key.

Methods

List Roles

Lists every role a member of this project can be given: the custom roles the project owns, plus the global, system-defined ones (projectId is null). Project roles govern access inside this project only; organization-wide settings come from the member's organization role.

from confident_ai import ConfidentAI

client = ConfidentAI()

project = client.project(project_id="<PROJECT-ID>")
result = project.list_roles()

For async mode, call a_list_roles and await it as shown below:

result = await project.a_list_roles(...)

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const project = client.project("<PROJECT-ID>");
const result = await project.listRoles();

Returns

This method returns an object of type ProjectRoleList.

Create Role

Creates a custom role in this project from a set of project policies and returns the role. Its permissions are the union of what those policies grant, so a role created with an empty policyIds can do nothing until you attach one, and it grants nobody anything until a project member is assigned to it.

from confident_ai import ConfidentAI

client = ConfidentAI()

project = client.project(project_id="<PROJECT-ID>")
result = project.create_role(
    name="Billing Auditor",
    policy_ids=["<POLICY-ID>"],
    description="Read-only access to invoices and model costs.",
)

For async mode, call a_create_role and await it as shown below:

result = await project.a_create_role(...)

Parameters

Parameter	Type	Description
`name`	`str`	Required. The name of the role, unique among the roles the organization or project can use. It cannot match the name of a global, system-defined role, compared without regard to case.
`policy_ids`	`List[str]`	Required. The ids of the policies to attach to the role, which is what gives the role its permissions. This is the role's complete policy set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the role with no permissions at all. Discover assignable policies with the policies endpoint of the same scope.
`description`	`Optional[str]`	What the role is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const project = client.project("<PROJECT-ID>");
const result = await project.createRole(
  "Billing Auditor",
  ["<POLICY-ID>"],
  { description: "Read-only access to invoices and model costs." },
);

Parameters

Parameter	Type	Description
`name`	`string`	Required. The name of the role, unique among the roles the organization or project can use. It cannot match the name of a global, system-defined role, compared without regard to case.
`policyIds`	`string[]`	Required. The ids of the policies to attach to the role, which is what gives the role its permissions. This is the role's complete policy set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the role with no permissions at all. Discover assignable policies with the policies endpoint of the same scope.
`description`	`string \| null`	What the role is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

Returns

This method returns an object of type ProjectRole.

Update Role

Replaces a custom project role's name, description, and attached policies. Every member holding the role is affected immediately, since permissions are resolved on each request. A global, system-defined role responds 404.

from confident_ai import ConfidentAI

client = ConfidentAI()

project = client.project(project_id="<PROJECT-ID>")
result = project.update_role(
    role_id="<ROLE-ID>",
    name="Billing Auditor",
    policy_ids=["<POLICY-ID>"],
    description="Read-only access to invoices and model costs.",
)

For async mode, call a_update_role and await it as shown below:

result = await project.a_update_role(...)

Parameters

Parameter	Type	Description
`role_id`	`str`	Required. The id of the project role. It must be a role the project owns; a global, system-defined role is not addressable here.
`name`	`str`	Required. The name of the role, unique among the roles the organization or project can use. It cannot match the name of a global, system-defined role, compared without regard to case.
`policy_ids`	`List[str]`	Required. The ids of the policies to attach to the role, which is what gives the role its permissions. This is the role's complete policy set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the role with no permissions at all. Discover assignable policies with the policies endpoint of the same scope.
`description`	`Optional[str]`	What the role is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const project = client.project("<PROJECT-ID>");
const result = await project.updateRole(
  "<ROLE-ID>",
  "Billing Auditor",
  ["<POLICY-ID>"],
  { description: "Read-only access to invoices and model costs." },
);

Parameters

Parameter	Type	Description
`roleId`	`string`	Required. The id of the project role. It must be a role the project owns; a global, system-defined role is not addressable here.
`name`	`string`	Required. The name of the role, unique among the roles the organization or project can use. It cannot match the name of a global, system-defined role, compared without regard to case.
`policyIds`	`string[]`	Required. The ids of the policies to attach to the role, which is what gives the role its permissions. This is the role's complete policy set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the role with no permissions at all. Discover assignable policies with the policies endpoint of the same scope.
`description`	`string \| null`	What the role is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

Returns

This method returns an object of type ProjectRole.

Delete Role

Permanently deletes a custom project role. A role still assigned to at least one member cannot be deleted — move those members onto another role first — so deleting a role never silently strips anyone of their access. The policies attached to it are not deleted and stay available to other roles in the project. A global, system-defined role responds 404. This cannot be undone.

from confident_ai import ConfidentAI

client = ConfidentAI()

project = client.project(project_id="<PROJECT-ID>")
result = project.delete_role(role_id="<ROLE-ID>")

For async mode, call a_delete_role and await it as shown below:

result = await project.a_delete_role(...)

Parameters

Parameter	Type	Description
`role_id`	`str`	Required. The id of the project role. It must be a role the project owns; a global, system-defined role is not addressable here.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const project = client.project("<PROJECT-ID>");
const result = await project.deleteRole("<ROLE-ID>");

Parameters

Parameter	Type	Description
`roleId`	`string`	Required. The id of the project role. It must be a role the project owns; a global, system-defined role is not addressable here.

Returns

This method returns an object of type RoleRef.

Methods (Stateless)

These methods take every argument themselves, so a caller reaches them through client.projects without opening a Project first.

List Roles

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.projects.list_roles(project_id="<PROJECT-ID>")

For async mode, call a_list_roles and await it as shown below:

result = await client.projects.a_list_roles(...)

Parameters

Parameter	Type	Description
`project_id`	`str`	Required. The id of the project, which must belong to your organization.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.projects.listRoles("<PROJECT-ID>");

Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The id of the project, which must belong to your organization.

Returns

This method returns an object of type ProjectRoleList.

Create Role

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.projects.create_role(
    project_id="<PROJECT-ID>",
    name="Billing Auditor",
    policy_ids=["<POLICY-ID>"],
    description="Read-only access to invoices and model costs.",
)

For async mode, call a_create_role and await it as shown below:

result = await client.projects.a_create_role(...)

Parameters

Parameter	Type	Description
`project_id`	`str`	Required. The id of the project, which must belong to your organization.
`name`	`str`	Required. The name of the role, unique among the roles the organization or project can use. It cannot match the name of a global, system-defined role, compared without regard to case.
`policy_ids`	`List[str]`	Required. The ids of the policies to attach to the role, which is what gives the role its permissions. This is the role's complete policy set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the role with no permissions at all. Discover assignable policies with the policies endpoint of the same scope.
`description`	`Optional[str]`	What the role is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.projects.createRole(
  "<PROJECT-ID>",
  "Billing Auditor",
  ["<POLICY-ID>"],
  { description: "Read-only access to invoices and model costs." },
);

Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The id of the project, which must belong to your organization.
`name`	`string`	Required. The name of the role, unique among the roles the organization or project can use. It cannot match the name of a global, system-defined role, compared without regard to case.
`policyIds`	`string[]`	Required. The ids of the policies to attach to the role, which is what gives the role its permissions. This is the role's complete policy set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the role with no permissions at all. Discover assignable policies with the policies endpoint of the same scope.
`description`	`string \| null`	What the role is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

Returns

This method returns an object of type ProjectRole.

Update Role

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.projects.update_role(
    project_id="<PROJECT-ID>",
    role_id="<ROLE-ID>",
    name="Billing Auditor",
    policy_ids=["<POLICY-ID>"],
    description="Read-only access to invoices and model costs.",
)

For async mode, call a_update_role and await it as shown below:

result = await client.projects.a_update_role(...)

Parameters

Parameter	Type	Description
`project_id`	`str`	Required. The id of the project the role belongs to.
`role_id`	`str`	Required. The id of the project role. It must be a role the project owns; a global, system-defined role is not addressable here.
`name`	`str`	Required. The name of the role, unique among the roles the organization or project can use. It cannot match the name of a global, system-defined role, compared without regard to case.
`policy_ids`	`List[str]`	Required. The ids of the policies to attach to the role, which is what gives the role its permissions. This is the role's complete policy set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the role with no permissions at all. Discover assignable policies with the policies endpoint of the same scope.
`description`	`Optional[str]`	What the role is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.projects.updateRole(
  "<PROJECT-ID>",
  "<ROLE-ID>",
  "Billing Auditor",
  ["<POLICY-ID>"],
  { description: "Read-only access to invoices and model costs." },
);

Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The id of the project the role belongs to.
`roleId`	`string`	Required. The id of the project role. It must be a role the project owns; a global, system-defined role is not addressable here.
`name`	`string`	Required. The name of the role, unique among the roles the organization or project can use. It cannot match the name of a global, system-defined role, compared without regard to case.
`policyIds`	`string[]`	Required. The ids of the policies to attach to the role, which is what gives the role its permissions. This is the role's complete policy set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the role with no permissions at all. Discover assignable policies with the policies endpoint of the same scope.
`description`	`string \| null`	What the role is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

Returns

This method returns an object of type ProjectRole.

Delete Role

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.projects.delete_role(
    project_id="<PROJECT-ID>",
    role_id="<ROLE-ID>",
)

For async mode, call a_delete_role and await it as shown below:

result = await client.projects.a_delete_role(...)

Parameters

Parameter	Type	Description
`project_id`	`str`	Required. The id of the project the role belongs to.
`role_id`	`str`	Required. The id of the project role. It must be a role the project owns; a global, system-defined role is not addressable here.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.projects.deleteRole(
  "<PROJECT-ID>",
  "<ROLE-ID>",
);

Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The id of the project the role belongs to.
`roleId`	`string`	Required. The id of the project role. It must be a role the project owns; a global, system-defined role is not addressable here.

Returns

This method returns an object of type RoleRef.

Types

ProjectRole

A named set of project policies that a project member can hold. A member holds at most one role per project, and every permission they have in that project comes from the policies attached to it.

class ProjectRole:
    id: str
    name: str
    description: Optional[str]
    policies: List[RolePolicy]
    project_id: Optional[str] = Field(alias="projectId")

idstrRequired

The id of the role, generated by Confident AI.

Example: "<ROLE-ID>"

namestrRequired

The name of the role.

Example: "Release Manager"

descriptionOptional[str]Required

What the role is for, or null when it has no description.

Example: "Can publish prompts and run evaluations, but not delete data."

policiesList[RolePolicy]Required

The project policies attached to the role, whose permissions together are everything a member holding it can do in the project. A global role's permissions are system-defined rather than drawn from policies, so its list is empty.

See RolePolicy.

project_idOptional[str]Required

The id of the project that owns the role, or null for a global, system-defined role that every project can assign.

Example: "<PROJECT-ID>"

interface ProjectRole {
  id: string;
  name: string;
  description: string | null;
  policies: RolePolicy[];
  projectId: string | null;
}

idstringRequired

The id of the role, generated by Confident AI.

Example: "<ROLE-ID>"

namestringRequired

The name of the role.

Example: "Release Manager"

descriptionstring | nullRequired

What the role is for, or null when it has no description.

Example: "Can publish prompts and run evaluations, but not delete data."

policiesRolePolicy[]Required

See RolePolicy.

projectIdstring | nullRequired

The id of the project that owns the role, or null for a global, system-defined role that every project can assign.

Example: "<PROJECT-ID>"

ProjectRoleList

Every project role a member can be given in this project, owned and global together.

class ProjectRoleList:
    roles: List[ProjectRole]

rolesList[ProjectRole]Required

The roles this project can assign: the roles it owns, plus the global, system-defined roles available to every project.

See ProjectRole.

interface ProjectRoleList {
  roles: ProjectRole[];
}

rolesProjectRole[]Required

The roles this project can assign: the roles it owns, plus the global, system-defined roles available to every project.

See ProjectRole.

RolePolicy

A policy attached to a role, by id and name. The permissions it grants are not listed here; retrieve the policy from the policies endpoint of the same scope (GET /v2/organization/policies or GET /v2/projects/{projectId}/policies) to see them.

class RolePolicy:
    id: str
    name: str

idstrRequired

The id of the policy, generated by Confident AI.

Example: "<POLICY-ID>"

namestrRequired

The name of the policy.

Example: "Billing read-only"

interface RolePolicy {
  id: string;
  name: string;
}

idstringRequired

The id of the policy, generated by Confident AI.

Example: "<POLICY-ID>"

namestringRequired

The name of the policy.

Example: "Billing read-only"

RoleRef

Confirmation that the role no longer exists.

class RoleRef:
    id: str

idstrRequired

The id of the role that was deleted.

Example: "<ROLE-ID>"

interface RoleRef {
  id: string;
}

idstringRequired

The id of the role that was deleted.

Example: "<ROLE-ID>"

Building a production pipeline?Design a scalable API workflow for evals, datasets, traces, and promptsTalk to an engineer

Last updated on September 30, 2026

Built byConfident AI