Policies

Overview

The Confident AI SDK exposes every Policy 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 Policies

Lists the custom access policies your organization owns, each with the permissions it grants. These are what you attach to organization roles; the global, system-defined roles do not draw their permissions from policies.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.organization.list_policies()

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

result = await client.organization.a_list_policies(...)

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.organization.listPolicies();

Returns

This method returns an object of type PolicyList.

Create Policy

Creates a custom organization policy from a set of permissions and returns it. A policy on its own grants nobody anything: it takes effect only once it is attached to an organization role, and then applies to every member holding that role.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.organization.create_policy(
    name="Billing read-only",
    permission_ids=["<PERMISSION-ID>"],
    description="Lets a role read invoices and model costs, but change neither.",
)

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

result = await client.organization.a_create_policy(...)

Parameters

Parameter	Type	Description
`name`	`str`	Required. The name of the policy, unique within the organization or project that owns it. It is what identifies the policy when attaching it to a role.
`permission_ids`	`List[str]`	Required. The ids of the permissions this policy grants. This is the policy's complete permission set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the policy granting nothing. Discover assignable ids with the permissions endpoint of the same scope; an id from the other scope's catalog is stored but never matches a permission check here.
`description`	`Optional[str]`	What the policy 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.createPolicy(
  "Billing read-only",
  ["<PERMISSION-ID>"],
  {
    description: "Lets a role read invoices and model costs, but change neither."
  },
);

Parameters

Parameter	Type	Description
`name`	`string`	Required. The name of the policy, unique within the organization or project that owns it. It is what identifies the policy when attaching it to a role.
`permissionIds`	`string[]`	Required. The ids of the permissions this policy grants. This is the policy's complete permission set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the policy granting nothing. Discover assignable ids with the permissions endpoint of the same scope; an id from the other scope's catalog is stored but never matches a permission check here.
`description`	`string \| null`	What the policy 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 Policy.

Update Policy

Replaces an organization policy's name, description, and granted permissions. The change reaches people through the roles the policy is attached to, and it reaches them immediately: every member holding any of those roles gains or loses the affected permissions on their next call.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.organization.update_policy(
    policy_id="<POLICY-ID>",
    name="Billing read-only",
    permission_ids=["<PERMISSION-ID>"],
    description="Lets a role read invoices and model costs, but change neither.",
)

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

result = await client.organization.a_update_policy(...)

Parameters

Parameter	Type	Description
`policy_id`	`str`	Required. The id of the policy.
`name`	`str`	Required. The name of the policy, unique within the organization or project that owns it. It is what identifies the policy when attaching it to a role.
`permission_ids`	`List[str]`	Required. The ids of the permissions this policy grants. This is the policy's complete permission set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the policy granting nothing. Discover assignable ids with the permissions endpoint of the same scope; an id from the other scope's catalog is stored but never matches a permission check here.
`description`	`Optional[str]`	What the policy 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.updatePolicy(
  "<POLICY-ID>",
  "Billing read-only",
  ["<PERMISSION-ID>"],
  {
    description: "Lets a role read invoices and model costs, but change neither."
  },
);

Parameters

Parameter	Type	Description
`policyId`	`string`	Required. The id of the policy.
`name`	`string`	Required. The name of the policy, unique within the organization or project that owns it. It is what identifies the policy when attaching it to a role.
`permissionIds`	`string[]`	Required. The ids of the permissions this policy grants. This is the policy's complete permission set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the policy granting nothing. Discover assignable ids with the permissions endpoint of the same scope; an id from the other scope's catalog is stored but never matches a permission check here.
`description`	`string \| null`	What the policy 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 Policy.

Delete Policy

Permanently deletes an organization policy. Unlike a role, a policy in use is not protected: it is detached from every organization role holding it, and members of those roles lose the permissions it granted on their next request. The permissions themselves survive, as do the roles — though a role left with no policies can do nothing. List the organization's roles first to see which carry this policy.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.organization.delete_policy(policy_id="<POLICY-ID>")

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

result = await client.organization.a_delete_policy(...)

Parameters

Parameter	Type	Description
`policy_id`	`str`	Required. The id of the policy.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.organization.deletePolicy("<POLICY-ID>");

Parameters

Parameter	Type	Description
`policyId`	`string`	Required. The id of the policy.

Returns

This method returns an object of type PolicyRef.

Types

Policy

A named set of permissions owned by an organization or by a project. A policy is attached to roles of the same scope, never to a member directly, so it only grants anything once a role that holds it is assigned to someone.

class Policy:
    id: str
    name: str
    description: Optional[str]
    permissions: List[PolicyPermission]

idstrRequired

The id of the policy, generated by Confident AI.

Example: "<POLICY-ID>"

namestrRequired

The name of the policy.

Example: "Billing read-only"

descriptionOptional[str]Required

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

Example: "Lets a role read invoices and model costs, but change neither."

permissionsList[PolicyPermission]Required

The permissions this policy grants.

See PolicyPermission.

interface Policy {
  id: string;
  name: string;
  description: string | null;
  permissions: PolicyPermission[];
}

idstringRequired

The id of the policy, generated by Confident AI.

Example: "<POLICY-ID>"

namestringRequired

The name of the policy.

Example: "Billing read-only"

descriptionstring | nullRequired

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

Example: "Lets a role read invoices and model costs, but change neither."

permissionsPolicyPermission[]Required

The permissions this policy grants.

See PolicyPermission.

PolicyList

The policies available to attach to the roles of the same organization or project.

class PolicyList:
    policies: List[Policy]

policiesList[Policy]Required

The custom policies the organization or project owns.

See Policy.

interface PolicyList {
  policies: Policy[];
}

policiesPolicy[]Required

The custom policies the organization or project owns.

See Policy.

PolicyPermission

A permission granted by a policy. Its name is a resource:action pair such as billing:read or dataset:read; the permissions endpoint of the same scope (GET /v2/organization/permissions or GET /v2/projects/{projectId}/permissions) lists every pair a policy there can grant.

class PolicyPermission:
    id: str
    name: str

idstrRequired

The id of the permission, generated by Confident AI.

Example: "<PERMISSION-ID>"

namestrRequired

The permission, written as resource:action — the resource it applies to, then what it allows on it.

Example: "billing:read"

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

idstringRequired

The id of the permission, generated by Confident AI.

Example: "<PERMISSION-ID>"

namestringRequired

The permission, written as resource:action — the resource it applies to, then what it allows on it.

Example: "billing:read"

PolicyRef

Confirmation that the policy no longer exists.

class PolicyRef:
    id: str

idstrRequired

The id of the policy that was deleted.

Example: "<POLICY-ID>"

interface PolicyRef {
  id: string;
}

idstringRequired

The id of the policy that was deleted.

Example: "<POLICY-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