Roles

albert.collections.roles.RoleCollection

RoleCollection(*, session: AlbertSession)

Bases: BaseCollection

Manage Roles in the Albert platform.

A Role defines a set of access permissions (policies) within a tenant. Roles are assigned to users (User) to govern what they can do, and are referenced by entity ACLs alongside the users they apply to.

This collection is accessed as client.roles.

Example

from albert import Albert
client = Albert()
roles = client.roles.get_all()
for role in roles:
    print(role.id, role.name)

Parameters:

Name	Type	Description	Default
session	AlbertSession	The authenticated Albert session used for API calls.	required

Attributes:

Name	Type	Description
base_path	str	The base API route for role requests.

Methods:

Name	Description
get_by_id	Get a single role by its ID.
get_all	Get all available roles.
create	Create a new role.

Parameters:

Name	Type	Description	Default
session	AlbertSession	The authenticated Albert session used for API calls.	required

Source code in src/albert/collections/roles.py

def __init__(self, *, session: AlbertSession):
    """Initialize a RoleCollection.

    Parameters
    ----------
    session : AlbertSession
        The authenticated Albert session used for API calls.
    """
    super().__init__(session=session)
    self.base_path = f"/api/{RoleCollection._api_version}/acl/roles"

base_path

base_path = f'/api/{RoleCollection._api_version}/acl/roles'

get_by_id

get_by_id(*, id: str) -> Role

Get a single role by its ID.

Example

role = client.roles.get_by_id(id="role#admin")
role.name
# 'Administrator'

Parameters:

Name	Type	Description	Default
id	str	The ID of the role. Role IDs may contain # characters and are URL-encoded automatically.	required

Returns:

Type	Description
Role	The fully populated role.

Source code in src/albert/collections/roles.py

def get_by_id(self, *, id: str) -> Role:
    """Get a single role by its ID.

    !!! example
        ```python
        role = client.roles.get_by_id(id="role#admin")
        role.name
        # 'Administrator'
        ```

    Parameters
    ----------
    id : str
        The ID of the role. Role IDs may contain ``#`` characters and are
        URL-encoded automatically.

    Returns
    -------
    Role
        The fully populated role.
    """
    # role IDs have # symbols
    url = urllib.parse.quote(f"{self.base_path}/{id}")
    response = self.session.get(url=url)
    return Role(**response.json())

create

create(*, role: Role)

Create a new role.

Example

from albert.resources.roles import Role
role = client.roles.create(role=Role(name="Lab Analyst", tenant="TEN123"))
role.id

Parameters:

Name	Type	Description	Default
role	Role	The role to create.	required

Returns:

Type	Description
Role	The newly created role.

Source code in src/albert/collections/roles.py

def create(self, *, role: Role):
    """Create a new role.

    !!! example
        ```python
        from albert.resources.roles import Role
        role = client.roles.create(role=Role(name="Lab Analyst", tenant="TEN123"))
        role.id
        ```

    Parameters
    ----------
    role : Role
        The role to create.

    Returns
    -------
    Role
        The newly created role.
    """
    response = self.session.post(
        self.base_path,
        json=role.model_dump(by_alias=True, exclude_none=True, mode="json"),
    )
    return Role(**response.json())

get_all

get_all(*, params: dict | None = None) -> list[Role]

Get all available roles.

Example

roles = client.roles.get_all()
[r.name for r in roles]
# ['Administrator', 'Standard User']

Parameters:

Name	Type	Description	Default
params	dict	Optional query parameters passed through to the API to filter or shape the results. Defaults to no parameters.	None

Returns:

Type	Description
list[Role]	All roles available in the tenant.

Source code in src/albert/collections/roles.py

def get_all(self, *, params: dict | None = None) -> list[Role]:
    """Get all available roles.

    !!! example
        ```python
        roles = client.roles.get_all()
        [r.name for r in roles]
        # ['Administrator', 'Standard User']
        ```

    Parameters
    ----------
    params : dict, optional
        Optional query parameters passed through to the API to filter or
        shape the results. Defaults to no parameters.

    Returns
    -------
    list[Role]
        All roles available in the tenant.
    """
    if params is None:
        params = {}
    response = self.session.get(self.base_path, params=params)
    role_data = response.json().get("Items", [])
    return [Role(**r) for r in role_data]