api_client

api_client

ApiClient_ScopeEnum

Bases: DomoEnumMixin, Enum

Valid scopes for API client access.

Scopes define what resources and operations an API client can access. Multiple scopes can be assigned to a single API client.

create_api_client async

create_api_client(
    auth: DomoFullAuth,
    client_name: str,
    client_description: str = f"generated via DL {replace('-', '')}",
    scope: list[ApiClient_ScopeEnum] | None = None,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs,
) -> ResponseGetData

Create a new API client (developer token) with specified scopes.

Creates a new API client with the provided name, description, and scopes. This operation requires DomoFullAuth (username and password authentication).

Parameters:

Name	Type	Description	Default
auth	DomoFullAuth	DomoFullAuth object (username and password required)	required
client_name	str	Name for the new API client	required
client_description	str	Optional description for the API client	f'generated via DL {replace('-', '')}'
scope	list[ApiClient_ScopeEnum] | None	list of ApiClient_ScopeEnum values, defaults to [data, audit]	None
context	RouteContext | None	Optional RouteContext for request configuration	None
return_raw	bool	Return raw API response without processing	False
**context_kwargs		Additional context parameters (session, debug_api, etc.)	{}

Returns:

Type	Description
ResponseGetData	ResponseGetData object containing the newly created API client data

Raises:

Type	Description
InvalidAuthTypeError	If auth is not DomoFullAuth
ApiClient_CRUD_Error	If API client creation fails

Source code in src/crew_dcs/routes/instance_config/api_client.py

@gd.route_function
@log_call(
    level_name="route",
    config=LogDecoratorConfig(
        entity_extractor=DomoEntityExtractor(),
        result_processor=DomoEntityResultProcessor(),
    ),
)
async def create_api_client(
    auth: DomoFullAuth,  # username and password (full) auth required for this API
    client_name: str,
    client_description: str = f"generated via DL {str(dt.date.today()).replace('-', '')}",
    scope: list[ApiClient_ScopeEnum] | None = None,  # defaults to [data, audit]
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs,
) -> rgd.ResponseGetData:
    """
    Create a new API client (developer token) with specified scopes.

    Creates a new API client with the provided name, description, and scopes.
    This operation requires DomoFullAuth (username and password authentication).

    Args:
        auth: DomoFullAuth object (username and password required)
        client_name: Name for the new API client
        client_description: Optional description for the API client
        scope: list of ApiClient_ScopeEnum values, defaults to [data, audit]
        context: Optional RouteContext for request configuration
        return_raw: Return raw API response without processing
        **context_kwargs: Additional context parameters (session, debug_api, etc.)

    Returns:
        ResponseGetData object containing the newly created API client data

    Raises:
        InvalidAuthTypeError: If auth is not DomoFullAuth
        ApiClient_CRUD_Error: If API client creation fails
    """
    context = RouteContext.build_context(context=context, **context_kwargs)

    if not isinstance(auth, DomoFullAuth):
        raise InvalidAuthTypeError(
            message=f"required auth type {DomoFullAuth.__name__}"
        )

    if scope and isinstance(scope, list):
        scope = [dmue.normalize_enum(sc) for sc in scope]

    if not scope:
        scope = ["data", "audit"]

    url = "https://api.domo.com/clients"

    headers = {"X-DOMO-CustomerDomain": f"{auth.domo_instance}.domo.com"}

    res = await gd.get_data(
        url=url,
        method="POST",
        auth=auth,
        body={"name": client_name, "description": client_description, "scope": scope},
        headers=headers,
        context=context,
    )

    if return_raw:
        return res

    if not res.is_success:
        if res.status == 400:
            raise ApiClient_CRUD_Error(
                operation="create",
                res=res,
                message=f"{res.response} -- does the client already exist?",
            )

        # if res.status == 403: # invalid auth type, but will be caught by the earlier test

        raise ApiClient_CRUD_Error(operation="create", res=res)

    return res

get_api_clients async

get_api_clients(
    auth: DomoAuth,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs
) -> ResponseGetData

Retrieve all API clients (developer tokens) for the authenticated instance.

Fetches a list of all API clients associated with the current Domo instance. Each client includes metadata such as name, description, scopes, and ID.

Parameters:

Name	Type	Description	Default
auth	DomoAuth	Authentication object containing instance and credentials	required
context	RouteContext | None	Optional RouteContext for request configuration	None
return_raw	bool	Return raw API response without processing	False
**context_kwargs		Additional context parameters (session, debug_api, etc.)	{}

Returns:

Type	Description
ResponseGetData	ResponseGetData object containing list of API clients

Raises:

Type	Description
ApiClient_GET_Error	If API client retrieval fails

Source code in src/crew_dcs/routes/instance_config/api_client.py

@gd.route_function
@log_call(
    level_name="route",
    config=LogDecoratorConfig(
        entity_extractor=DomoEntityExtractor(),
        result_processor=DomoEntityResultProcessor(),
    ),
)
async def get_api_clients(
    auth: DomoAuth,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs,
) -> rgd.ResponseGetData:
    """
    Retrieve all API clients (developer tokens) for the authenticated instance.

    Fetches a list of all API clients associated with the current Domo instance.
    Each client includes metadata such as name, description, scopes, and ID.

    Args:
        auth: Authentication object containing instance and credentials
        context: Optional RouteContext for request configuration
        return_raw: Return raw API response without processing
        **context_kwargs: Additional context parameters (session, debug_api, etc.)

    Returns:
        ResponseGetData object containing list of API clients

    Raises:
        ApiClient_GET_Error: If API client retrieval fails
    """
    context = RouteContext.build_context(context=context, **context_kwargs)

    url = f"https://{auth.domo_instance}.domo.com/api/identity/v1/developer-tokens"

    res = await gd.get_data(
        url=url,
        method="GET",
        auth=auth,
        context=context,
    )

    if return_raw:
        return res

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

    # API response change 6/10/2025
    # res.response = res.response["entries"]

    return res

get_client_by_id async

get_client_by_id(
    auth: DomoAuth,
    client_id: int,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs
) -> ResponseGetData

Retrieve a specific API client by its ID.

Fetches details of a single API client identified by the provided client_id. This function internally calls get_api_clients and filters the results.

Parameters:

Name	Type	Description	Default
auth	DomoAuth	Authentication object containing instance and credentials	required
client_id	int	Unique identifier for the API client	required
context	RouteContext | None	Optional RouteContext for request configuration	None
return_raw	bool	Return raw API response without processing	False
**context_kwargs		Additional context parameters (session, debug_api, etc.)	{}

Returns:

Type	Description
ResponseGetData	ResponseGetData object containing the specific API client data

Raises:

Type	Description
ApiClient_GET_Error	If API client retrieval fails
StopIteration	If no client with the specified ID is found

Source code in src/crew_dcs/routes/instance_config/api_client.py

@gd.route_function
@log_call(
    level_name="route",
    config=LogDecoratorConfig(
        entity_extractor=DomoEntityExtractor(),
        result_processor=DomoEntityResultProcessor(),
    ),
)
async def get_client_by_id(
    auth: DomoAuth,
    client_id: int,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs,
) -> rgd.ResponseGetData:
    """
    Retrieve a specific API client by its ID.

    Fetches details of a single API client identified by the provided client_id.
    This function internally calls get_api_clients and filters the results.

    Args:
        auth: Authentication object containing instance and credentials
        client_id: Unique identifier for the API client
        context: Optional RouteContext for request configuration
        return_raw: Return raw API response without processing
        **context_kwargs: Additional context parameters (session, debug_api, etc.)

    Returns:
        ResponseGetData object containing the specific API client data

    Raises:
        ApiClient_GET_Error: If API client retrieval fails
        StopIteration: If no client with the specified ID is found
    """
    context = RouteContext.build_context(context=context, **context_kwargs)

    res = await get_api_clients(
        auth=auth,
        context=context,
    )

    if return_raw:
        return res

    client = next(obj for obj in res.response if obj.get("id") == int(client_id))
    res.response = client
    return res

revoke_api_client async

revoke_api_client(
    auth: DomoAuth,
    client_id: str,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs
) -> ResponseGetData

Revoke (delete) an existing API client by its ID.

Permanently revokes an API client, invalidating its credentials and preventing further API access.

Parameters:

Name	Type	Description	Default
auth	DomoAuth	Authentication object containing instance and credentials	required
client_id	str	Unique identifier for the API client to revoke	required
return_raw	bool	Return raw API response without processing	False
context	RouteContext | None	RouteContext for request configuration	None
**context_kwargs		Additional context parameters (session, debug_api, etc.)	{}

Returns:

Type	Description
ResponseGetData	ResponseGetData object with confirmation message

Raises:

Type	Description
ApiClient_RevokeError	If API client revocation fails

Source code in src/crew_dcs/routes/instance_config/api_client.py

@gd.route_function
@log_call(
    level_name="route",
    config=LogDecoratorConfig(
        entity_extractor=DomoEntityExtractor(),
        result_processor=DomoEntityResultProcessor(),
    ),
)
async def revoke_api_client(
    auth: DomoAuth,
    client_id: str,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs,
) -> rgd.ResponseGetData:
    """
    Revoke (delete) an existing API client by its ID.

    Permanently revokes an API client, invalidating its credentials and
    preventing further API access.

    Args:
        auth: Authentication object containing instance and credentials
        client_id: Unique identifier for the API client to revoke
        return_raw: Return raw API response without processing
        context: RouteContext for request configuration
        **context_kwargs: Additional context parameters (session, debug_api, etc.)

    Returns:
        ResponseGetData object with confirmation message

    Raises:
        ApiClient_RevokeError: If API client revocation fails
    """
    context = RouteContext.build_context(context=context, **context_kwargs)

    url = f"https://{auth.domo_instance}.domo.com/api/identity/v1/developer-tokens/{client_id}"

    res = await gd.get_data(
        url=url,
        method="DELETE",
        auth=auth,
        context=context,
    )

    if return_raw:
        return res

    if not res.is_success:
        if res.status == 400:
            raise ApiClient_RevokeError(
                client_id=client_id,
                res=res,
                message=f"Error revoking client {client_id}, validate that it exists.",
            )
        raise ApiClient_RevokeError(client_id=client_id, res=res)

    res.response = f"client {client_id} revoked"

    return res