bayesline.api.PermissionsApi

bayesline.api.PermissionsApi#

class bayesline.api.PermissionsApi#

Abstract base class for synchronous ACL-based permissionining API operations.

__init__()#

Methods

`__init__`()
`add_user_to_group`(group_id, user_id)	Add a user to a group.
`assign_role`(user_id, role_type)	Assign a role to a user.
`check_permission`(resource_id, ...[, ...])	Check if the current user has the required permission for a resource.
`create_group`(name, description)	Create a new user group.
`delete_group`(group_id)	Delete a user group.
`get_accessible_resources`(resource_type, ...)	Get all resources the current user can access with the required permission.
`get_shared_resource_summary`([resource_ids, ...])	Get a summary of the resources that the current user has shared with others.
`get_user_permissions`([resource_type, ...])	Get the current user's permissions for resources.
`grant_permission`(resource_id, ...[, ...])	Grant permission to a principal for a resource.
`has_any_role`(required_roles)	Check whether the current user satisfies any of the required roles.
`list_effective_roles`()	List every role the current user holds, expanded via the hierarchy.
`list_group_members`(group_id)	List members of a group.
`list_groups`()	List all groups the current user can see.
`list_user_roles`([user_id])	List roles assigned to a user.
`remove_user_from_group`(group_id, user_id)	Remove a user from a group.
`revoke_permission`(resource_id, ...[, ...])	Revoke permission from a principal for a resource.
`revoke_role`(user_id, role_type)	Revoke a role from a user.
`update_group`(group_id, description)	Update a group's description.
`update_permission`(resource_id, ...[, ...])	Update permission level for a principal on a resource.

abstract get_user_permissions(resource_type: ResourceType | None = None, resource_ids: Sequence[int] | None = None) → UserPermissionsSummary#

Get the current user’s permissions for resources.

Parameters#

resource_typeResourceType | None, default=None: Specific resource type to check. If None, returns permissions for all accessible resources.
resource_idsSequence[int] | None, default=None: Specific resource IDs to check. If None or empty, returns permissions for all accessible resources. IDs that do not exist, or that the current user has no permission on, are silently ignored rather than raising: they are simply absent from the result.

Returns#

UserPermissionsSummary: Summary of the user’s permissions.

abstract check_permission(resource_id: int, required_permission: PermissionLevel, *, resource_type: ResourceType = ResourceType.SETTING) → bool#

Check if the current user has the required permission for a resource.

Parameters#

resource_idint: The ID of the resource to check.
required_permissionPermissionLevel: The required permission level.
resource_typeResourceType, default=ResourceType.SETTING: The type of the resource.

Returns#

bool: True if the user has the required permission, False otherwise.

abstract get_accessible_resources(resource_type: ResourceType, required_permission: PermissionLevel) → Sequence[int]#

Get all resources the current user can access with the required permission.

Parameters#

resource_typeResourceType: The type of resources to check.
required_permissionPermissionLevel: The minimum permission level required.

Returns#

Sequence[int]: List of resource IDs the user can access.

abstract grant_permission(resource_id: int, principal_type: PrincipalType, principal_id: str, permission_level: PermissionLevel, *, resource_type: ResourceType = ResourceType.SETTING) → None#

Grant permission to a principal for a resource.

Ensure-at-least semantics: an existing entry is only raised to a higher level, never lowered (use update_permission to lower or deny). The current user must have ADMIN permission on the resource; for FEATURE_FLAG resources (which have no owner) an admin role (ADMIN, BUSINESS_ADMIN, or TECH_ADMIN) authorizes instead.

Parameters#

resource_idint: The ID of the resource.
principal_typePrincipalType: The type of principal (user, group, role).
principal_idstr: The ID of the principal. For a USER principal this may be the user’s id or email; group and role principals are keyed by name.
permission_levelPermissionLevel: The permission level to grant.
resource_typeResourceType, default=ResourceType.SETTING: The type of the resource.

Raises#

PermissionDeniedError: If the current user doesn’t have ADMIN permission on the resource.
PrincipalNotFoundError: If the principal is a USER and no user matches the given id or email.
ACLValidationError: If permission_level is NONE on a resource type other than FEATURE_FLAG - only feature flags resolve NONE as a deny.

abstract revoke_permission(resource_id: int, principal_type: PrincipalType, principal_id: str, *, resource_type: ResourceType = ResourceType.SETTING) → None#

Revoke permission from a principal for a resource.

The current user must have ADMIN permission on the resource; for FEATURE_FLAG resources (which have no owner) an admin role (ADMIN, BUSINESS_ADMIN, or TECH_ADMIN) authorizes instead.

Parameters#

resource_idint: The ID of the resource.
principal_typePrincipalType: The type of principal (user, group, role).
principal_idstr: The ID of the principal. For a USER principal this may be the user’s id or email; group and role principals are keyed by name.
resource_typeResourceType, default=ResourceType.SETTING: The type of the resource.

Raises#

PermissionDeniedError: If the current user doesn’t have ADMIN permission on the resource.
PrincipalNotFoundError: If the principal is a USER and no user matches the given id or email.

abstract update_permission(resource_id: int, principal_type: PrincipalType, principal_id: str, permission_level: PermissionLevel, *, resource_type: ResourceType = ResourceType.SETTING) → None#

Update permission level for a principal on a resource.

The current user must have ADMIN permission on the resource; for FEATURE_FLAG resources (which have no owner) an admin role (ADMIN, BUSINESS_ADMIN, or TECH_ADMIN) authorizes instead.

Parameters#

resource_idint: The ID of the resource.
principal_typePrincipalType: The type of principal (user, group, role).
principal_idstr: The ID of the principal. For a USER principal this may be the user’s id or email; group and role principals are keyed by name.
permission_levelPermissionLevel: The new permission level.
resource_typeResourceType, default=ResourceType.SETTING: The type of the resource.

Raises#

PermissionDeniedError: If the current user doesn’t have ADMIN permission on the resource.
PrincipalNotFoundError: If the principal is a USER and no user matches the given id or email.
ACLValidationError: If permission_level is NONE on a resource type other than FEATURE_FLAG - only feature flags resolve NONE as a deny.

abstract create_group(name: str, description: str) → int#

Create a new user group.

Parameters#

namestr: The name of the group.
descriptionstr: A description of the group.

Returns#

int: The ID of the created group.

abstract update_group(group_id: int, description: str) → None#

Update a group’s description.

The current user must be the creator of the group or have admin role.

Parameters#

group_idint: The ID of the group.
descriptionstr: The new description.

Raises#

PermissionDeniedError: If the current user doesn’t have permission to update the group.

abstract delete_group(group_id: int) → None#

Delete a user group.

The current user must be the creator of the group or have admin role.

Parameters#

group_idint: The ID of the group to delete.

Raises#

PermissionDeniedError: If the current user doesn’t have permission to delete the group.

abstract add_user_to_group(group_id: int, user_id: str) → None#

Add a user to a group.

The current user must be the creator of the group or have admin role.

Parameters#

group_idint: The ID of the group.
user_idUserRef: The user to add, given as a user id or email.

Raises#

PermissionDeniedError: If the current user doesn’t have permission to manage the group.
PrincipalNotFoundError: If no user matches the given id or email.

abstract remove_user_from_group(group_id: int, user_id: str) → None#

Remove a user from a group.

The current user must be the creator of the group or have admin role.

Parameters#

group_idint: The ID of the group.
user_idUserRef: The user to remove, given as a user id or email.

Raises#

PermissionDeniedError: If the current user doesn’t have permission to manage the group.
PrincipalNotFoundError: If no user matches the given id or email.

abstract list_groups() → Sequence[UserGroup]#

List all groups the current user can see.

Returns#

Sequence[UserGroup]: List of groups the user can see (created by them or they’re members of).

abstract list_group_members(group_id: int) → Sequence[GroupMembership]#

List members of a group.

The current user must be a member of the group, the creator, or have admin role.

Parameters#

group_idint: The ID of the group.

Returns#

Sequence[GroupMembership]: List of group memberships.

Raises#

PermissionDeniedError: If the current user doesn’t have permission to view group members.

abstract assign_role(user_id: str, role_type: RoleType) → None#

Assign a role to a user.

Only users with ADMIN role can assign roles.

Parameters#

user_idUserRef: The user, given as a user id or email.
role_typeRoleType: The role to assign.

Raises#

PermissionDeniedError: If the current user doesn’t have ADMIN role.
PrincipalNotFoundError: If no user matches the given id or email.

abstract revoke_role(user_id: str, role_type: RoleType) → None#

Revoke a role from a user.

Only users with ADMIN role can revoke roles.

Parameters#

user_idUserRef: The user, given as a user id or email.
role_typeRoleType: The role to revoke.

Raises#

PermissionDeniedError: If the current user doesn’t have ADMIN role.
PrincipalNotFoundError: If no user matches the given id or email.

abstract list_user_roles(user_id: str | None = None) → Sequence[UserRole]#

List roles assigned to a user.

Parameters#

user_idUserRef | None, default=None: The user, given as a user id or email. If None, lists roles for the current user.

Returns#

Sequence[UserRole]: List of user role assignments.

Raises#

PermissionDeniedError: If trying to view another user’s roles without ADMIN permission.
PrincipalNotFoundError: If a user id or email is given that matches no user.

abstract has_any_role(required_roles: Sequence[RoleType]) → bool#

Check whether the current user satisfies any of the required roles.

The role hierarchy is respected: a higher role in a ladder satisfies the roles below it, and ADMIN satisfies every role.

Parameters#

required_rolesSequence[RoleType]: The roles that would grant access. An empty sequence returns True.

Returns#

bool: True if the current user holds (directly or via the hierarchy) at least one of the required roles, False otherwise.

abstract list_effective_roles() → Sequence[RoleType]#

List every role the current user holds, expanded via the hierarchy.

Unlike list_user_roles(), this returns plain role types (not assignment records) and includes roles implied by the hierarchy: a directly assigned higher role contributes the roles below it in its ladder, and ADMIN contributes every role. This is intended for callers (e.g. the GUI) that need to decide whether to surface a role-gated affordance without reimplementing the hierarchy.

Returns#

Sequence[RoleType]: The current user’s effective roles.

abstract get_shared_resource_summary(resource_ids: Sequence[int] | None = None, *, resource_type: ResourceType = ResourceType.SETTING) → SharedResourceSummary#

Get a summary of the resources that the current user has shared with others.

Parameters#

resource_idsSequence[int] | None, default=None: Restrict the summary to these resource IDs. If None or empty, every shared resource is returned. IDs that do not exist, or that exist but the current user has not shared, are silently ignored rather than raising: they are simply absent from the result. A summary therefore never reports on a resource the caller asked about but has not shared, and the returned resources are always a subset of the requested IDs.
resource_typeResourceType, default=ResourceType.SETTING: The type of resources to summarize.

Returns#

SharedResourceSummary: A summary of the resources that the current user has shared. Empty if none of the requested resources are shared.

bayesline.api.PermissionsApi

Contents

bayesline.api.PermissionsApi#

Parameters#

Returns#

Parameters#

Returns#

Parameters#

Returns#

Parameters#

Raises#

Parameters#

Raises#

Parameters#

Raises#

Parameters#

Returns#

Parameters#

Raises#

Parameters#

Raises#

Parameters#

Raises#

Parameters#

Raises#

Returns#

Parameters#

Returns#

Raises#

Parameters#

Raises#

Parameters#

Raises#

Parameters#

Returns#

Raises#

Parameters#

Returns#

Returns#

Parameters#

Returns#