sift_client.resources.principal_attributes

CLASS	DESCRIPTION
PrincipalAttributesAPIAsync	High-level API for principal attributes (ABAC).

ATTRIBUTE	DESCRIPTION
ASSIGN_BATCH_SIZE

ASSIGN_BATCH_SIZE module-attribute

ASSIGN_BATCH_SIZE = 1000

PrincipalAttributesAPIAsync

PrincipalAttributesAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for principal attributes (ABAC).

Principal attributes assign attribute keys to principals (users or user groups). The attribute key is the entry point: enum values and assignments are managed through methods on a key, or through the corresponding methods here.

Initialize the PrincipalAttributesAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
get_key	Get a principal attribute key by ID.
list_keys	List principal attribute keys with optional filtering.
find_key	Find a single key matching the query. Raises if more than one matches.
create_key	Create a principal attribute key.
get_or_create_key	Get a key by display name, creating it if it does not exist.
update_key	Update a key's display name or description.
archive_key	Archive a key. Cascades to its enum values and assignments.
unarchive_key	Unarchive a key. Does not restore its cascaded enum values or assignments.
check_key_archive_impact	Return the number of active assignments archiving this key would affect.
create_enum_value	Create a single enum value for a key.
list_enum_values	List the enum values defined for a key.
get_or_create_enum_values	Get enum values for a key by name, creating any that don't exist.
archive_enum_value	Archive an enum value, migrating existing assignments to a replacement.
unarchive_enum_value	Unarchive an enum value.
assign	Assign a value to principals for a key.
get_assignment	Get a single assignment by ID.
list_assignments	List principal attribute assignments.
archive_assignments	Batch archive assignments.
unarchive_assignments	Batch unarchive assignments.
resolve_user_id	Resolve a user's email (its user name) to a user ID.
resolve_user_ids	Resolve user emails (their user names) to user IDs.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

get_key async

get_key(*, key_id: str) -> PrincipalAttributeKey

Get a principal attribute key by ID.

list_keys async

list_keys(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    value_type: PrincipalAttributeValueType | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[PrincipalAttributeKey]

List principal attribute keys with optional filtering.

PARAMETER	DESCRIPTION
name	Exact display name of the key. TYPE: str | None DEFAULT: None
names	Display names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Substring match on the display name. TYPE: str | None DEFAULT: None
name_regex	Regex match on the display name. TYPE: str | Pattern | None DEFAULT: None
value_type	Filter to keys of this value type. TYPE: PrincipalAttributeValueType | None DEFAULT: None
include_archived	If True, include archived keys. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query. TYPE: str | None DEFAULT: None
order_by	Field and direction to order by. TYPE: str | None DEFAULT: None
limit	Maximum number of keys to return. TYPE: int | None DEFAULT: None
page_size	Results to fetch per request. TYPE: int | None DEFAULT: None

find_key async

find_key(**kwargs) -> PrincipalAttributeKey | None

Find a single key matching the query. Raises if more than one matches.

create_key async

create_key(
    display_name: str,
    value_type: PrincipalAttributeValueType,
    *,
    description: str = "",
) -> PrincipalAttributeKey

Create a principal attribute key.

get_or_create_key async

get_or_create_key(
    display_name: str,
    value_type: PrincipalAttributeValueType,
    *,
    description: str = "",
) -> PrincipalAttributeKey

Get a key by display name, creating it if it does not exist.

Note

Display names are not guaranteed unique. If multiple keys share the display name, the first active match is returned.

update_key async

update_key(
    key: str | PrincipalAttributeKey,
    *,
    display_name: str | None = None,
    description: str | None = None,
) -> PrincipalAttributeKey

Update a key's display name or description.

archive_key async

archive_key(
    key: str | PrincipalAttributeKey,
) -> PrincipalAttributeKey

Archive a key. Cascades to its enum values and assignments.

unarchive_key async

unarchive_key(
    key: str | PrincipalAttributeKey,
) -> PrincipalAttributeKey

Unarchive a key. Does not restore its cascaded enum values or assignments.

check_key_archive_impact async

check_key_archive_impact(
    key: str | PrincipalAttributeKey,
) -> int

Return the number of active assignments archiving this key would affect.

Counts both user and user-group assignments.

create_enum_value async

create_enum_value(
    key: str | PrincipalAttributeKey,
    display_name: str,
    *,
    description: str = "",
) -> PrincipalAttributeEnumValue

Create a single enum value for a key.

list_enum_values async

list_enum_values(
    key: str | PrincipalAttributeKey,
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[PrincipalAttributeEnumValue]

List the enum values defined for a key.

get_or_create_enum_values async

get_or_create_enum_values(
    key: str | PrincipalAttributeKey, names: list[str]
) -> list[PrincipalAttributeEnumValue]

Get enum values for a key by name, creating any that don't exist.

Returns the values in the same order as names.

archive_enum_value async

archive_enum_value(
    enum_value: str | PrincipalAttributeEnumValue,
    *,
    replacement: str
    | PrincipalAttributeEnumValue
    | None = None,
) -> int

Archive an enum value, migrating existing assignments to a replacement.

Returns the number of assignments migrated.

unarchive_enum_value async

unarchive_enum_value(
    enum_value: str | PrincipalAttributeEnumValue,
) -> PrincipalAttributeEnumValue

Unarchive an enum value.

assign async

assign(
    key: PrincipalAttributeKey,
    principals: list[str],
    *,
    value: Any,
    principal_type: PrincipalType = USER,
) -> list[PrincipalAttributeValue]

Assign a value to principals for a key.

PARAMETER	DESCRIPTION
key	The key to assign. Its value_type determines how value is interpreted. TYPE: PrincipalAttributeKey
principals	Principal IDs. For USER principals, an entry containing @ is treated as an email and resolved to a user ID. TYPE: list[str]
value	For SET_OF_ENUM, a list of enum values (or their IDs) that becomes the full set on each principal; for ENUM, a single enum value; for BOOLEAN, a bool; for NUMBER, an int. TYPE: Any
principal_type	The kind of principal being assigned to. Defaults to USER. TYPE: PrincipalType DEFAULT: USER

RETURNS	DESCRIPTION
list[PrincipalAttributeValue]	The created assignments.

get_assignment async

get_assignment(
    *,
    assignment_id: str,
    principal_type: PrincipalType = USER,
) -> PrincipalAttributeValue

Get a single assignment by ID.

list_assignments async

list_assignments(
    *,
    key: str | PrincipalAttributeKey | None = None,
    principal: str | None = None,
    principal_type: PrincipalType = USER,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[PrincipalAttributeValue]

List principal attribute assignments.

PARAMETER	DESCRIPTION
key	Filter to assignments of this key. TYPE: str | PrincipalAttributeKey | None DEFAULT: None
principal	Filter to assignments for this principal (user ID, or email for users). TYPE: str | None DEFAULT: None
principal_type	The kind of principal to list assignments for. Defaults to USER. TYPE: PrincipalType DEFAULT: USER
include_archived	If True, include archived assignments. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query. TYPE: str | None DEFAULT: None
order_by	Field and direction to order by. TYPE: str | None DEFAULT: None
limit	Maximum number of assignments to return. TYPE: int | None DEFAULT: None
page_size	Results to fetch per request. TYPE: int | None DEFAULT: None

archive_assignments async

archive_assignments(
    assignments: list[str | PrincipalAttributeValue],
    *,
    principal_type: PrincipalType = USER,
) -> None

Batch archive assignments.

unarchive_assignments async

unarchive_assignments(
    assignments: list[str | PrincipalAttributeValue],
    *,
    principal_type: PrincipalType = USER,
) -> None

Batch unarchive assignments.

resolve_user_id async

resolve_user_id(email: str) -> str

Resolve a user's email (its user name) to a user ID.

RAISES	DESCRIPTION
ValueError	If no user with that email is found.

resolve_user_ids async

resolve_user_ids(emails: list[str]) -> dict[str, str]

Resolve user emails (their user names) to user IDs.

Returns a mapping of email to user ID for the emails that were found. Emails with no matching user are omitted.