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 organization role a member can be given: the custom roles your organization owns, plus the global, system-defined ones (organizationId is null). Each comes with the policies attached to it.
from confident_ai import ConfidentAI
client = ConfidentAI()
result = client.organization.list_roles()For async mode, call a_list_roles and await it as shown below:
result = await client.organization.a_list_roles(...)import { ConfidentAI } from "confident-ai";
const client = new ConfidentAI();
const result = await client.organization.listRoles();Returns
This method returns an object of type OrganizationRoleList.
Create Role
Creates a custom organization role from a set of organization 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 member is assigned to it.
from confident_ai import ConfidentAI
client = ConfidentAI()
result = client.organization.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 client.organization.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 result = await client.organization.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 OrganizationRole.
Update Role
Replaces a custom organization 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()
result = client.organization.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 client.organization.a_update_role(...)Parameters
| Parameter | Type | Description |
|---|---|---|
role_id | str | Required. The id of the role. It must be a role the organization or 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.organization.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 role. It must be a role the organization or 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 OrganizationRole.
Delete Role
Permanently deletes a custom organization 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. A global, system-defined role responds 404. This cannot be undone.
from confident_ai import ConfidentAI
client = ConfidentAI()
result = client.organization.delete_role(role_id="<ROLE-ID>")For async mode, call a_delete_role and await it as shown below:
result = await client.organization.a_delete_role(...)Parameters
| Parameter | Type | Description |
|---|---|---|
role_id | str | Required. The id of the role. It must be a role the organization or project owns; a global, system-defined role is not addressable here. |
import { ConfidentAI } from "confident-ai";
const client = new ConfidentAI();
const result = await client.organization.deleteRole("<ROLE-ID>");Parameters
| Parameter | Type | Description |
|---|---|---|
roleId | string | Required. The id of the role. It must be a role the organization or project owns; a global, system-defined role is not addressable here. |
Returns
This method returns an object of type RoleRef.
Types
OrganizationRole
A named set of organization policies that a member can hold. A member holds at most one organization role, and every organization permission they have comes from the policies attached to it.
class OrganizationRole:
id: str
name: str
description: Optional[str]
policies: List[RolePolicy]
organization_id: Optional[str] = Field(alias="organizationId")idstrRequired
The id of the role, generated by Confident AI.
Example: "<ROLE-ID>"
namestrRequired
The name of the role.
Example: "Billing Auditor"
descriptionOptional[str]Required
What the role is for, or null when it has no description.
Example: "Read-only access to invoices and model costs."
policiesList[RolePolicy]Required
The organization policies attached to the role, whose permissions together are everything a member holding it can do. A global role's permissions are system-defined rather than drawn from policies, so its list is empty.
See RolePolicy.
organization_idOptional[str]Required
The id of the organization that owns the role, or null for a global, system-defined role that every organization can assign.
Example: "<ORGANIZATION-ID>"
interface OrganizationRole {
id: string;
name: string;
description: string | null;
policies: RolePolicy[];
organizationId: string | null;
}idstringRequired
The id of the role, generated by Confident AI.
Example: "<ROLE-ID>"
namestringRequired
The name of the role.
Example: "Billing Auditor"
descriptionstring | nullRequired
What the role is for, or null when it has no description.
Example: "Read-only access to invoices and model costs."
policiesRolePolicy[]Required
The organization policies attached to the role, whose permissions together are everything a member holding it can do. A global role's permissions are system-defined rather than drawn from policies, so its list is empty.
See RolePolicy.
organizationIdstring | nullRequired
The id of the organization that owns the role, or null for a global, system-defined role that every organization can assign.
Example: "<ORGANIZATION-ID>"
OrganizationRoleList
Every organization role a member can be given, owned and global together.
class OrganizationRoleList:
roles: List[OrganizationRole]rolesList[OrganizationRole]Required
The roles your organization can assign: the roles it owns, plus the global, system-defined roles available to every organization.
See OrganizationRole.
interface OrganizationRoleList {
roles: OrganizationRole[];
}rolesOrganizationRole[]Required
The roles your organization can assign: the roles it owns, plus the global, system-defined roles available to every organization.
See OrganizationRole.
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: stridstrRequired
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: stridstrRequired
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>"
Last updated on