role

role

set_role_grants async

set_role_grants(
    auth: DomoAuth,
    role_id: str,
    grants: list[str],
    return_raw: bool = False,
    is_replace: bool = True,
    *,
    context: RouteContext | None = None,
    **context_kwargs
) -> ResponseGetData

REPLACES every authority on a role. Grants not in grants are removed.

The body is the bare list, PUT to the role's authorities collection — there is no add/remove delta. To add one grant, GET the role's current authorities and pass the merged list.

is_replace exists only so the request can be REFUSED rather than misunderstood. DomoRole.set_grants advertises the parameter, but it used to land in **context_kwargs and be dropped without a warning (client/context.py keeps a key only if hasattr(context, key), and RouteContext has no such field) — so is_replace=False silently replaced anyway, which is the exact opposite of what the caller asked for. Passing False now raises.

The name is left as set_role_grants: set_ already signals replacement, and it is a published name.

See .agents/guides/access-and-sharing.md.

Raises:

Type	Description
ValueError	if is_replace=False — this endpoint cannot merge.

Source code in src/crew_dcs/routes/role.py

@gd.route_function
@log_call(
    level_name="route",
    config=LogDecoratorConfig(
        entity_extractor=DomoEntityExtractor(),
        result_processor=DomoEntityResultProcessor(),
    ),
)
async def set_role_grants(
    auth: DomoAuth,
    role_id: str,
    grants: list[str],
    return_raw: bool = False,
    is_replace: bool = True,
    *,
    context: RouteContext | None = None,
    **context_kwargs,
) -> ResponseGetData:
    """REPLACES every authority on a role. Grants not in `grants` are removed.

    The body is the bare list, PUT to the role's authorities collection — there
    is no add/remove delta. To add one grant, GET the role's current authorities
    and pass the merged list.

    `is_replace` exists only so the request can be REFUSED rather than
    misunderstood. `DomoRole.set_grants` advertises the parameter, but it used
    to land in `**context_kwargs` and be dropped without a warning
    (client/context.py keeps a key only `if hasattr(context, key)`, and
    RouteContext has no such field) — so `is_replace=False` silently replaced
    anyway, which is the exact opposite of what the caller asked for. Passing
    False now raises.

    The name is left as `set_role_grants`: `set_` already signals replacement,
    and it is a published name.

    See `.agents/guides/access-and-sharing.md`.

    Raises:
        ValueError: if `is_replace=False` — this endpoint cannot merge.
    """
    if not is_replace:
        raise ValueError(
            "set_role_grants cannot merge: PUT .../authorities replaces every "
            "authority on the role. To add a grant, read the role's current "
            "authorities with get_role_grants and pass the merged list."
        )

    context = RouteContext.build_context(context=context, **context_kwargs)

    url = f"https://{auth.domo_instance}.domo.com/api/authorization/v1/roles/{role_id}/authorities"

    res = await gd.get_data(
        auth=auth,
        url=url,
        method="PUT",
        body=grants,
        context=context,
    )

    if return_raw:
        return res

    if res.status == 400 and res.response == "Bad Request":
        print(
            " 😕 weird API issue, but role should have been modified.  setting is_success = True \n"
        )
        res.is_success = True

    if not res.is_success:
        raise Role_CRUD_Error(res=res)

    return res