sift_client.resources.access_control.principal_attributes

CLASS	DESCRIPTION
PrincipalAttributesAPIAsync	High-level API for principal attributes.
PrincipalAttributeKeysAPIAsync	High-level API for principal attribute keys.
PrincipalAttributeEnumValuesAPIAsync	High-level API for the enum values defined on principal attribute keys.
PrincipalAttributeAssignmentsAPIAsync	High-level API for principal attribute assignments.

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 via keys, define enum values via enum_values when the key uses them, then assign a value to principals via assignments. Pass User objects, PrincipalRef references, or user email addresses; use PrincipalRef.user_group(...) for user groups.

Initialize the PrincipalAttributesAPI.

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

ATTRIBUTE	DESCRIPTION
keys	Nested keys API. See PrincipalAttributeKeysAPIAsync. TYPE: PrincipalAttributeKeysAPIAsync
enum_values	Nested enum values API. See PrincipalAttributeEnumValuesAPIAsync. TYPE: PrincipalAttributeEnumValuesAPIAsync
assignments	Nested assignments API. See PrincipalAttributeAssignmentsAPIAsync. TYPE: PrincipalAttributeAssignmentsAPIAsync
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

keys instance-attribute

keys: PrincipalAttributeKeysAPIAsync = (
    PrincipalAttributeKeysAPIAsync(sift_client)
)

Nested keys API. See PrincipalAttributeKeysAPIAsync.

enum_values instance-attribute

enum_values: PrincipalAttributeEnumValuesAPIAsync = (
    PrincipalAttributeEnumValuesAPIAsync(sift_client)
)

Nested enum values API. See PrincipalAttributeEnumValuesAPIAsync.

assignments instance-attribute

assignments: PrincipalAttributeAssignmentsAPIAsync = (
    PrincipalAttributeAssignmentsAPIAsync(sift_client)
)

Nested assignments API. See PrincipalAttributeAssignmentsAPIAsync.

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

PrincipalAttributeKeysAPIAsync

PrincipalAttributeKeysAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for principal attribute keys.

Accessed as a nested resource via client.access_control.principal_attributes.keys.

Initialize the PrincipalAttributeKeysAPI.

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

METHOD	DESCRIPTION
get	Get a principal attribute key by ID.
list_	List principal attribute keys with optional filtering.
find	Find a single key matching the query. Takes the same arguments as list_.
create	Create a principal attribute key.
get_or_create	Get a key by display name, creating it if it does not exist.
update	Update a key.
archive	Archive a key. Cascades to its enum values and assignments.
unarchive	Unarchive a key. Does not restore its cascaded enum values or assignments.
check_archive_impact	Check how many assignments archiving a key would affect.

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 async

get(*, key_id: str) -> PrincipalAttributeKey

Get a principal attribute key by ID.

PARAMETER	DESCRIPTION
key_id	The ID of the key. TYPE: str

RETURNS	DESCRIPTION
PrincipalAttributeKey	The key.

list_ async

list_(
    *,
    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,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by: str | None = None,
    modified_by: str | None = None,
    description_contains: str | 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
created_after	Filter to keys created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter to keys created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter to keys modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter to keys modified before this datetime. TYPE: datetime | None DEFAULT: None
created_by	Filter to keys created by this user ID. TYPE: str | None DEFAULT: None
modified_by	Filter to keys last modified by this user ID. TYPE: str | None DEFAULT: None
description_contains	Substring match on the description. TYPE: str | 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

RETURNS	DESCRIPTION
list[PrincipalAttributeKey]	The matching keys.

find async

find(**kwargs) -> PrincipalAttributeKey | None

Find a single key matching the query. Takes the same arguments as list_.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list_. DEFAULT: {}

RETURNS	DESCRIPTION
PrincipalAttributeKey | None	The key found, or None if no key matches.

RAISES	DESCRIPTION
ValueError	If more than one key matches.

create async

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

Create a principal attribute key.

PARAMETER	DESCRIPTION
display_name	The human-readable name of the key. TYPE: str
value_type	The value type of the key. TYPE: PrincipalAttributeValueType
description	Optional description. TYPE: str DEFAULT: ''

RETURNS	DESCRIPTION
PrincipalAttributeKey	The created key.

get_or_create async

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

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

PARAMETER	DESCRIPTION
display_name	The human-readable name of the key. TYPE: str
value_type	The value type used if the key is created. TYPE: PrincipalAttributeValueType
description	Optional description used if the key is created. TYPE: str DEFAULT: ''

RETURNS	DESCRIPTION
PrincipalAttributeKey	The existing or newly created key.

Note

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

update async

update(
    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

RETURNS	DESCRIPTION
PrincipalAttributeKey	The updated key.

archive async

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

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

PARAMETER	DESCRIPTION
key	The key or key ID to archive. TYPE: str | PrincipalAttributeKey

RETURNS	DESCRIPTION
PrincipalAttributeKey	The archived key.

unarchive async

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

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

PARAMETER	DESCRIPTION
key	The key or key ID to unarchive. TYPE: str | PrincipalAttributeKey

RETURNS	DESCRIPTION
PrincipalAttributeKey	The unarchived key.

check_archive_impact async

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

Check how many assignments archiving a key would affect.

Counts both user and user-group assignments.

PARAMETER	DESCRIPTION
key	The key or key ID to check. TYPE: str | PrincipalAttributeKey

RETURNS	DESCRIPTION
int	The number of active assignments archiving this key would affect.

PrincipalAttributeEnumValuesAPIAsync

PrincipalAttributeEnumValuesAPIAsync(
    sift_client: SiftClient,
)

Bases: ResourceBase

High-level API for the enum values defined on principal attribute keys.

Accessed as a nested resource via client.access_control.principal_attributes.enum_values.

Initialize the PrincipalAttributeEnumValuesAPI.

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

METHOD	DESCRIPTION
create	Create a single enum value for a key.
list_	List the enum values defined for a key.
get_or_create	Get enum values for a key by name, creating any that don't exist.
archive	Archive an enum value, migrating existing assignments to a replacement.
unarchive	Unarchive an enum value.

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

create async

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

Create a single enum value for a key.

PARAMETER	DESCRIPTION
key	The key or key ID the enum value belongs to. TYPE: str | PrincipalAttributeKey
display_name	The human-readable name of the enum value. TYPE: str
description	Optional description. TYPE: str DEFAULT: ''

RETURNS	DESCRIPTION
PrincipalAttributeEnumValue	The created enum value.

list_ async

list_(
    key: str | PrincipalAttributeKey,
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by: str | None = None,
    modified_by: str | None = None,
    description_contains: str | 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.

PARAMETER	DESCRIPTION
key	The key or key ID to list enum values for. TYPE: str | PrincipalAttributeKey
name	Exact display name of the enum value. 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
created_after	Filter to enum values created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter to enum values created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter to enum values modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter to enum values modified before this datetime. TYPE: datetime | None DEFAULT: None
created_by	Filter to enum values created by this user ID. TYPE: str | None DEFAULT: None
modified_by	Filter to enum values last modified by this user ID. TYPE: str | None DEFAULT: None
description_contains	Substring match on the description. TYPE: str | None DEFAULT: None
include_archived	If True, include archived enum values. 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 enum values to return. TYPE: int | None DEFAULT: None
page_size	Results to fetch per request. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[PrincipalAttributeEnumValue]	The matching enum values.

get_or_create async

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

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

PARAMETER	DESCRIPTION
key	The key or key ID the enum values belong to. TYPE: str | PrincipalAttributeKey
names	Display names of the enum values to get or create. TYPE: list[str]

RETURNS	DESCRIPTION
list[PrincipalAttributeEnumValue]	The enum values, in the same order as names.

archive async

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

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

PARAMETER	DESCRIPTION
enum_value	The enum value or enum value ID to archive. TYPE: str | PrincipalAttributeEnumValue
replacement	Optional enum value or enum value ID that existing assignments are migrated to. TYPE: str | PrincipalAttributeEnumValue | None DEFAULT: None

RETURNS	DESCRIPTION
int	The number of assignments migrated.

unarchive async

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

Unarchive an enum value.

PARAMETER	DESCRIPTION
enum_value	The enum value or enum value ID to unarchive. TYPE: str | PrincipalAttributeEnumValue

RETURNS	DESCRIPTION
PrincipalAttributeEnumValue	The unarchived enum value.

PrincipalAttributeAssignmentsAPIAsync

PrincipalAttributeAssignmentsAPIAsync(
    sift_client: SiftClient,
)

Bases: ResourceBase

High-level API for principal attribute assignments.

Accessed as a nested resource via client.access_control.principal_attributes.assignments.

Initialize the PrincipalAttributeAssignmentsAPI.

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

METHOD	DESCRIPTION
create	Assign a key's value to principals.
get	Get a single assignment by ID and principal type.
list_	List principal attribute assignments.
archive	Batch archive assignments of the given principal type.
unarchive	Batch unarchive assignments of the given principal type.

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

create async

create(
    key: str | PrincipalAttributeKey,
    principals: list[PrincipalRef | User | str],
    *,
    value: PrincipalAttributeValueLike,
) -> 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	Principals to assign to. Pass PrincipalRef.user(...) / PrincipalRef.user_group(...) references, User objects, or user email addresses (resolved to user IDs automatically). Bare IDs are rejected because they do not say which kind of principal they refer to. TYPE: list[PrincipalRef | User | 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

RETURNS	DESCRIPTION
list[PrincipalAttributeAssignment]	The created assignments, one per enum value per principal for
list[PrincipalAttributeAssignment]	SET_OF_ENUM keys. Order is not guaranteed to match the input order.

get async

get(
    *, assignment_id: str, principal_type: PrincipalType
) -> PrincipalAttributeAssignment

Get a single assignment by ID and principal type.

PARAMETER	DESCRIPTION
assignment_id	The ID of the assignment. TYPE: str
principal_type	The kind of principal the assignment applies to. TYPE: PrincipalType

RETURNS	DESCRIPTION
PrincipalAttributeAssignment	The assignment.

list_ async

list_(
    *,
    key: str | PrincipalAttributeKey | None = None,
    principal: PrincipalRef | User | str | None = None,
    principal_type: PrincipalType | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    created_by: str | 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[PrincipalAttributeAssignment]

List principal attribute assignments.

For SET_OF_ENUM keys, each enum value is returned as its own assignment.

PARAMETER	DESCRIPTION
key	Filter to assignments of this key. TYPE: str | PrincipalAttributeKey | None DEFAULT: None
principal	Filter to assignments for this principal. Pass a PrincipalRef, a User object, or a user email address. TYPE: PrincipalRef | User | str | None DEFAULT: None
principal_type	The kind of principal to list assignments for when principal is not given. Defaults to USER. When principal is given, its own type is used and this must match it if set. TYPE: PrincipalType | None DEFAULT: None
created_after	Filter to assignments created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter to assignments created before this datetime. TYPE: datetime | None DEFAULT: None
created_by	Filter to assignments created by this user ID. TYPE: str | None DEFAULT: None
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

RETURNS	DESCRIPTION
list[PrincipalAttributeAssignment]	The matching assignments.

RAISES	DESCRIPTION
ValueError	If principal_type conflicts with the type of principal.

archive async

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

Batch archive assignments of the given principal type.

PARAMETER	DESCRIPTION
assignments	The assignments or assignment IDs to archive. TYPE: list[str | PrincipalAttributeAssignment]
principal_type	The kind of principal the assignments apply to. TYPE: PrincipalType

unarchive async

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

Batch unarchive assignments of the given principal type.

PARAMETER	DESCRIPTION
assignments	The assignments or assignment IDs to unarchive. TYPE: list[str | PrincipalAttributeAssignment]
principal_type	The kind of principal the assignments apply to. TYPE: PrincipalType