sift_client.resources.access_control.principal_attributes

CLASS	DESCRIPTION
PrincipalAttributesAPIAsync	High-level API for principal attributes.

PrincipalAttributesAPIAsync

PrincipalAttributesAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for principal attributes.

Principal attributes describe the users or groups an access decision applies to. A principal is the "who" in an access decision, such as a user or user group.

Create or fetch an attribute key, define enum values when the key uses them, then assign a value to principals. User principals accept either user IDs or email addresses; user-group principals use user-group IDs.

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.
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 key's value to principals.
get_assignment	Get a single assignment by ID.
list_assignments	List principal attribute assignments.
archive_assignments	Batch archive assignments.
unarchive_assignments	Batch unarchive assignments.

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,
    update: PrincipalAttributeKeyUpdate | dict,
) -> PrincipalAttributeKey

Update a key.

PARAMETER	DESCRIPTION
key	The key or key ID to update. TYPE: str | PrincipalAttributeKey
update	Updates to apply to the key. TYPE: PrincipalAttributeKeyUpdate | dict

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: str | PrincipalAttributeKey,
    principals: list[str],
    *,
    value: PrincipalAttributeValueLike,
    principal_type: PrincipalType = USER,
) -> list[PrincipalAttributeAssignment]

Assign a key's value to principals.

PARAMETER	DESCRIPTION
key	The key or key ID to assign. Its value_type determines how value is interpreted. TYPE: str | PrincipalAttributeKey
principals	Principal IDs. For USER principals, entries containing @ are treated as email addresses and resolved to user IDs. 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: PrincipalAttributeValueLike
principal_type	The kind of principal being assigned to. Defaults to USER. Use PrincipalType.USER_GROUP when assigning to user groups. TYPE: PrincipalType DEFAULT: USER

RETURNS	DESCRIPTION
list[PrincipalAttributeAssignment]	The created assignments.

get_assignment async

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

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[PrincipalAttributeAssignment]

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. Use a user ID or email address for users; use a user-group ID with PrincipalType.USER_GROUP for user groups. 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 | PrincipalAttributeAssignment],
    *,
    principal_type: PrincipalType = USER,
) -> None

Batch archive assignments.

unarchive_assignments async

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

Batch unarchive assignments.