Retrieve a principal

async AsyncCogniteClient.iam.principals.retrieve(
id: str | SequenceNotStr[str] | None = None,
external_id: str | SequenceNotStr[str] | None = None,
ignore_unknown_ids: bool = False,
) → Principal | PrincipalList | None

Retrieve principal by reference in the organization.

Parameters:

  • id (str | SequenceNotStr[str] | None) – The ID(s) of the principal(s) to retrieve.

  • external_id (str | SequenceNotStr[str] | None) – The external ID(s) of the principal to retrieve.

  • ignore_unknown_ids (bool) – This is only relevant when retrieving multiple principals. If set to True, the method will return the principals that were found and ignore the ones that were not found. If set to False, the method will raise a CogniteAPIError if any of the specified principals were not found. Defaults to False.

Returns:

The principal(s) with the specified ID(s) or external ID(s).

Return type:

Principal | PrincipalList | None

Examples

Retrieve a principal by ID:
>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> res = client.iam.principals.retrieve(id="20u3of8-1234-5678-90ab-cdef12345678")
Retrieve a principal by external ID:
>>> res = client.iam.principals.retrieve(external_id="my_external_id")