Identity and access management

Compare access rights (capabilities)

Verify my capabilities

Helper method to compare your current capabilities with a set of desired capabilities and return any missing.

Parameters:

desired_capabilities (ComparableCapability) – List of desired capabilities to check against existing.
ignore_allscope_meaning (bool) – Option on how to treat allScopes. When True, this function will return e.g. an Acl scoped to a dataset even if the user have the same Acl scoped to all. Defaults to False.

Returns:

A flattened list of the missing capabilities, meaning they each have exactly 1 action, 1 scope, 1 id etc.

Return type:

list[Capability]

Examples

Ensure that the user’s credentials have access to read- and write assets in all scope, and write events scoped to a specific dataset with id=123:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.capabilities import AssetsAcl, EventsAcl
>>> client = CogniteClient()
>>> to_check = [
...     AssetsAcl(
...         actions=[AssetsAcl.Action.Read, AssetsAcl.Action.Write],
...         scope=AssetsAcl.Scope.All()),
...     EventsAcl(
...         actions=[EventsAcl.Action.Write],
...         scope=EventsAcl.Scope.DataSet([123]),
... )]
>>> if missing := client.iam.verify_capabilities(to_check):
...     pass  # do something

Capabilities can also be passed as dictionaries:

>>> to_check = [
...     {'assetsAcl': {'actions': ['READ', 'WRITE'], 'scope': {'all': {}}}},
...     {'eventsAcl': {'actions': ['WRITE'], 'scope': {'datasetScope': {'ids': [123]}}}},
... ]
>>> missing = client.iam.verify_capabilities(to_check)

You may also load capabilities from a dict-representation directly into ACLs (access-control list) by using Capability.load. This will also ensure that the capabilities are valid.

>>> from cognite.client.data_classes.capabilities import Capability
>>> acls = [Capability.load(cap) for cap in to_check]

Compare capabilities

Helper method to compare capabilities across two groups (of capabilities) to find which are missing from the first.

Note

Capabilities that are no longer in use by the API will be ignored. These have names prefixed with Legacy and all inherit from the base class LegacyCapability. If you want to check for these, you must do so manually.

Parameters:

existing_capabilities (ComparableCapability) – List of existing capabilities.
desired_capabilities (ComparableCapability) – List of wanted capabilities to check against existing.
project (str | None) – If a ProjectCapability or ProjectCapabilityList is passed, we need to know which CDF project to pull capabilities from (existing might be from several). If project is not passed, and ProjectCapabilityList is used, it will be inferred from the CogniteClient used to call retrieve it via token/inspect.
ignore_allscope_meaning (bool) – Option on how to treat scopes that encompass other scopes, like allScope. When True, this function will return e.g. an Acl scoped to a dataset even if the user have the same Acl scoped to all. The same logic applies to RawAcl scoped to a specific database->table, even when the user have access to all tables in that database. Defaults to False.

Returns:

A flattened list of the missing capabilities, meaning they each have exactly 1 action, 1 scope, 1 id etc.

Return type:

list[Capability]

Examples

Ensure that a user’s groups grant access to read- and write for assets in all scope, and events write, scoped to a specific dataset with id=123:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.capabilities import AssetsAcl, EventsAcl
>>> client = CogniteClient()
>>> my_groups = client.iam.groups.list(all=False)
>>> to_check = [
...     AssetsAcl(
...         actions=[AssetsAcl.Action.Read, AssetsAcl.Action.Write],
...         scope=AssetsAcl.Scope.All()),
...     EventsAcl(
...         actions=[EventsAcl.Action.Write],
...         scope=EventsAcl.Scope.DataSet([123]),
... )]
>>> missing = client.iam.compare_capabilities(
...     existing_capabilities=my_groups,
...     desired_capabilities=to_check)
>>> if missing:
...     pass  # do something

Capabilities can also be passed as dictionaries:

>>> to_check = [
...     {'assetsAcl': {'actions': ['READ', 'WRITE'], 'scope': {'all': {}}}},
...     {'eventsAcl': {'actions': ['WRITE'], 'scope': {'datasetScope': {'ids': [123]}}}},
... ]
>>> missing = client.iam.compare_capabilities(
...     existing_capabilities=my_groups,
...     desired_capabilities=to_check)

You may also load capabilities from a dict-representation directly into ACLs (access-control list) by using Capability.load. This will also ensure that the capabilities are valid.

>>> from cognite.client.data_classes.capabilities import Capability
>>> acls = [Capability.load(cap) for cap in to_check]

Tip

If you just want to check against your existing capabilities, you may use the helper method client.iam.verify_capabilities instead.

Principals

Get the current caller’s principal

PrincipalsAPI.me() → Principal

Get the current caller’s information.

Returns:

The principal of the user running the code, i.e. the: principal this CogniteClient was instantiated with.

Return type:

Principal

Examples

Get your own principal:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.iam.principals.me()

Retrieve a principal

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()
>>> 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")

List principals

PrincipalsAPI.list( types: str | SequenceNotStr[str] | None = None, limit: int = 25, ) → PrincipalList

List principals in the organization

Parameters:

types (str | SequenceNotStr[str] | None) – Filter by principal type(s). Defaults to None, which means no filtering.
limit (int) – The maximum number of principals to return. Defaults to DEFAULT_LIMIT_READ.

Returns:

The principal of the user running the code, i.e. the principal this CogniteClient was instantiated with.

Return type:

PrincipalList

Examples

List principals in the organization:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.iam.principals.list(types="USER", limit=10)

Tokens

Inspect the token currently used by the client

TokenAPI.inspect() → TokenInspection

Inspect a token.

Get details about which projects it belongs to and which capabilities are granted to it.

Returns:: The object with token inspection details.
Return type:: TokenInspection

Example

Inspect token:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.iam.token.inspect()

Groups

List groups

GroupsAPI.list(all: bool = False) → GroupList

List groups.

Parameters:: all (bool) – Whether to get all groups, only available with the groups:list acl.
Returns:: List of groups.
Return type:: GroupList

Example

List your own groups:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> my_groups = client.iam.groups.list()

List all groups:

>>> all_groups = client.iam.groups.list(all=True)

Create groups

GroupsAPI.create( group: Group | GroupWrite | Sequence[Group] | Sequence[GroupWrite], ) → Group | GroupList

Create one or more groups.

Parameters:: group (Group | GroupWrite | Sequence[Group] | Sequence[GroupWrite]) – Group or list of groups to create.
Returns:: The created group(s).
Return type:: Group | GroupList

Example

Create a group without any members:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import GroupWrite
>>> from cognite.client.data_classes.capabilities import AssetsAcl, EventsAcl
>>> client = CogniteClient()
>>> my_capabilities = [
...     AssetsAcl([AssetsAcl.Action.Read], AssetsAcl.Scope.All()),
...     EventsAcl([EventsAcl.Action.Write], EventsAcl.Scope.DataSet([123, 456]))]
>>> my_group = GroupWrite(name="My Group", capabilities=my_capabilities)
>>> res = client.iam.groups.create(my_group)

Create a group whose members are managed externally (by your company’s identity provider (IdP)). This is done by using the source_id field. If this is the same ID as a group in the IdP, a user in that group will implicitly be a part of this group as well.

>>> grp = GroupWrite(
...     name="Externally managed group",
...     capabilities=my_capabilities,
...     source_id="b7c9a5a4...")
>>> res = client.iam.groups.create(grp)

Create a group whose members are managed internally by Cognite. This group may grant access through listing specific users or include them all. This is done by passing the members field, either a list of strings with the unique user identifiers or as the constant ALL_USER_ACCOUNTS. To find the user identifiers, you may use the UserProfilesAPI: client.iam.user_profiles.list().

>>> from cognite.client.data_classes import ALL_USER_ACCOUNTS
>>> all_group = GroupWrite(
...     name="Everyone is welcome!",
...     capabilities=my_capabilities,
...     members=ALL_USER_ACCOUNTS,
... )
>>> user_list_group = GroupWrite(
...     name="Specfic users only",
...     capabilities=my_capabilities,
...     members=["XRsSD1k3mTIKG", "M0SxY6bM9Jl"])
>>> res = client.iam.groups.create([user_list_group, all_group])

Capabilities are often defined in configuration files, like YAML or JSON. You may convert capabilities from a dict-representation directly into ACLs (access-control list) by using Capability.load. This will also ensure that the capabilities are valid.

>>> from cognite.client.data_classes.capabilities import Capability
>>> unparsed_capabilities = [
...     {'assetsAcl': {'actions': ['READ', 'WRITE'], 'scope': {'all': {}}}},
...     {'eventsAcl': {'actions': ['WRITE'], 'scope': {'datasetScope': {'ids': [123]}}}},
... ]
>>> acls = [Capability.load(cap) for cap in unparsed_capabilities]
>>> group = GroupWrite(name="Another group", capabilities=acls)

Delete groups

GroupsAPI.delete(id: int | Sequence[int]) → None

Delete one or more groups.

Parameters:: id (int | Sequence[int]) – ID or list of IDs of groups to delete.

Example

Delete group:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.iam.groups.delete(1)

Security categories

List security categories

SecurityCategoriesAPI.list( limit: int | None = 25, ) → SecurityCategoryList

List security categories.

Parameters:: limit (int | None) – Max number of security categories to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
Returns:: List of security categories
Return type:: SecurityCategoryList

Example

List security categories:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.iam.security_categories.list()

Create security categories

SecurityCategoriesAPI.create( security_category: SecurityCategory | SecurityCategoryWrite | Sequence[SecurityCategory] | Sequence[SecurityCategoryWrite], ) → SecurityCategory | SecurityCategoryList

Create one or more security categories.

Parameters:: security_category (SecurityCategory | SecurityCategoryWrite | Sequence[SecurityCategory] | Sequence[SecurityCategoryWrite]) – Security category or list of categories to create.
Returns:: The created security category or categories.
Return type:: SecurityCategory | SecurityCategoryList

Example

Create security category:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import SecurityCategoryWrite
>>> client = CogniteClient()
>>> my_category = SecurityCategoryWrite(name="My Category")
>>> res = client.iam.security_categories.create(my_category)

Delete security categories

SecurityCategoriesAPI.delete(id: int | Sequence[int]) → None

Delete one or more security categories.

Parameters:: id (int | Sequence[int]) – ID or list of IDs of security categories to delete.

Example

Delete security category:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.iam.security_categories.delete(1)

Sessions

List sessions

SessionsAPI.list( status: Literal['READY', 'ACTIVE', 'CANCELLED', 'EXPIRED', 'REVOKED', 'ACCESS_LOST'] | None = None, limit: int = 25, ) → SessionList

List all sessions in the current project.

Parameters:

status (SessionStatus | None) – If given, only sessions with the given status are returned.
limit (int) – Max number of sessions to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.

Returns:

a list of sessions in the current project.

Return type:

SessionList

Create a session

SessionsAPI.create( client_credentials: ClientCredentials | None = None, session_type: Literal['CLIENT_CREDENTIALS', 'TOKEN_EXCHANGE', 'ONESHOT_TOKEN_EXCHANGE', 'DEFAULT'] = 'DEFAULT', ) → CreatedSession

Create a session.

Parameters:

client_credentials (ClientCredentials | None) – The client credentials to create the session. This is required if session_type is set to ‘CLIENT_CREDENTIALS’.
session_type (SessionType | Literal['DEFAULT']) – The type of session to create. Can be either ‘CLIENT_CREDENTIALS’, ‘TOKEN_EXCHANGE’, ‘ONESHOT_TOKEN_EXCHANGE’ or ‘DEFAULT’. Defaults to ‘DEFAULT’ which will use -this- CogniteClient object to create the session. If this client was created using a token, ‘TOKEN_EXCHANGE’ will be used, and if this client was created using client credentials, ‘CLIENT_CREDENTIALS’ will be used.

Session Types:

client_credentials: Credentials for a session using client credentials from an identity provider.

token_exchange: Credentials for a session using token exchange to reuse the user’s credentials.

one_shot_token_exchange: Credentials for a session using one-shot token exchange to reuse the user’s credentials. One-shot sessions are short-lived sessions that are not refreshed and do not require support for token exchange from the identity provider.

Returns:: The object with token inspection details.
Return type:: CreatedSession

Retrieve a session

SessionsAPI.retrieve( id: int | Sequence[int], ) → Session | SessionList

Retrieves sessions with given IDs.

The request will fail if any of the IDs does not belong to an existing session.

Parameters:: id (int | Sequence[int]) – Id or list of session ids
Returns:: Session or list of sessions.
Return type:: Session | SessionList

Revoke a session

SessionsAPI.revoke( id: int | Sequence[int], ) → Session | SessionList

Revoke access to a session. Revocation of a session may in some cases take up to 1 hour to take effect.

Parameters:: id (int | Sequence[int]) – Id or list of session ids
Returns:: List of revoked sessions. If the user does not have the sessionsAcl:LIST capability, then only the session IDs will be present in the response.
Return type:: Session | SessionList

User Profiles

Enable user profiles for project

UserProfilesAPI.enable() → UserProfilesConfiguration: Enable user profiles for the project

Disable user profiles for project

UserProfilesAPI.disable() → UserProfilesConfiguration: Disable user profiles for the project

Get my own user profile

UserProfilesAPI.me() → UserProfile

Retrieve your own user profile

Retrieves the user profile of the principal issuing the request, i.e. the principal this CogniteClient was instantiated with.

Returns:: Your own user profile.
Return type:: UserProfile
Raises:: CogniteAPIError – If this principal doesn’t have a user profile, you get a not found (404) response code.

Examples

Get your own user profile:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.iam.user_profiles.me()

List user profiles

UserProfilesAPI.list( limit: int | None = 25, ) → UserProfileList

List user profiles

List all user profiles in the current CDF project. The results are ordered alphabetically by name.

Parameters:: limit (int | None) – Maximum number of user profiles to return. Defaults to 25. Set to -1, float(“inf”) or None to return all.
Returns:: List of user profiles.
Return type:: UserProfileList

Examples

List all user profiles:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.iam.user_profiles.list(limit=None)

Retrieve one or more user profiles

UserProfilesAPI.retrieve( user_identifier: str | SequenceNotStr[str], ) → UserProfile | UserProfileList | None

Retrieve user profiles by user identifier.

Retrieves one or more user profiles indexed by the user identifier in the same CDF project.

Parameters:: user_identifier (str | SequenceNotStr[str]) – The single user identifier (or sequence of) to retrieve profile(s) for.
Returns:: UserProfileList if a sequence of user identifier were requested, else UserProfile. If a single user identifier is requested and it is not found, None is returned.
Return type:: UserProfile | UserProfileList | None
Raises:: CogniteNotFoundError – A sequences of user identifiers were requested, but one or more does not exist.

Examples

Get a single user profile:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.iam.user_profiles.retrieve("foo")

Get multiple user profiles:

>>> res = client.iam.user_profiles.retrieve(["bar", "baz"])

Search for user profiles

UserProfilesAPI.search( name: str, limit: int = 25, ) → UserProfileList

Search for user profiles Primarily meant for human-centric use-cases and data exploration, not for programs, as the result set ordering and match criteria threshold may change over time.

Parameters:

name (str) – Prefix search on name.
limit (int) – Maximum number of results to return.

Returns:

User profiles search result

Return type:

UserProfileList

Examples

Search for users with first (or second…) name starting with “Alex”:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.iam.user_profiles.search(name="Alex")

Data classes

class cognite.client.data_classes.iam.ClientCredentials(client_id: str, client_secret: str)

Bases: CogniteResource

Client credentials for session creation

Parameters:

client_id (str) – Client ID from identity provider.
client_secret (str) – Client secret from identity provider.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]

class cognite.client.data_classes.iam.CreatedSession( id: int, status: Literal['READY', 'ACTIVE', 'CANCELLED', 'EXPIRED', 'REVOKED', 'ACCESS_LOST'], nonce: str, type: Literal['CLIENT_CREDENTIALS', 'TOKEN_EXCHANGE', 'ONESHOT_TOKEN_EXCHANGE'] | None = None, client_id: str | None = None, )

Bases: CogniteResponse

Session creation related information

Parameters:

id (int) – ID of the created session.
status (SessionStatus) – Current status of the session.
nonce (str) – Nonce to be passed to the internal service that will bind the session
type (SessionType | None) – Credentials kind used to create the session.
client_id (str | None) – Client ID in identity provider. Returned only if the session was created using client credentials

Bases: GroupCore

Groups are used to give principals the capabilities to access CDF resources. One principal can be a member in multiple groups and one group can have multiple members.

Groups can either be managed through the external identity provider for the project or managed by CDF.

Parameters:

name (str) – Name of the group.
source_id (str | None) – ID of the group in the source. If this is the same ID as a group in the IdP, a service account in that group will implicitly be a part of this group as well. Can not be used together with ‘members’.
capabilities (list[Capability] | None) – List of capabilities (acls) this group should grant its users.
attributes (GroupAttributes | None) – Attributes of the group, this scopes down access based on the attributes specified.
id (int | None) – No description.
is_deleted (bool | None) – No description.
deleted_time (int | None) – No description.
metadata (dict[str, str] | None) – Custom, immutable application specific metadata. String key -> String value. Limits: Key are at most 32 bytes. Values are at most 512 bytes. Up to 16 key-value pairs. Total size is at most 4096.
members (Literal['allUserAccounts'] | list[str] | None) – Specifies which users are members of the group. Can not be used together with ‘source_id’.
cognite_client (CogniteClient | None) – No description.

as_write() → GroupWrite: Returns a writing version of this group.

to_pandas( expand_metadata: bool = False, metadata_prefix: str = 'metadata.', ignore: list[str] | None = None, camel_case: bool = False, convert_timestamps: bool = True, ) → pd.DataFrame

Convert the instance into a pandas DataFrame.

Parameters:

expand_metadata (bool) – Expand the metadata into separate rows (default: False).
metadata_prefix (str) – Prefix to use for the metadata rows, if expanded.
ignore (list[str] | None) – List of row keys to skip when converting to a data frame. Is applied before expansions.
camel_case (bool) – Convert attribute names to camel case (e.g. externalId instead of external_id). Does not affect custom data like metadata if expanded.
convert_timestamps (bool) – Convert known attributes storing CDF timestamps (milliseconds since epoch) to datetime. Does not affect custom data like metadata.

Returns:

The dataframe.

Return type:

pandas.DataFrame

class cognite.client.data_classes.iam.GroupAttributes( token: GroupAttributesToken | None = None, )

Bases: CogniteObject

Attributes derived from access token

dump(camel_case: bool = True) → dict[str, Any]: Dumps the attributes to a dictionary

class cognite.client.data_classes.iam.GroupAttributesToken(app_ids: list[str] = <factory>)

Bases: CogniteObject

List of applications (represented by their application ID) this group is valid for

Bases: WriteableCogniteResource[GroupWrite], ABC

No description.

Parameters:

name (str) – Name of the group.
source_id (str | None) – ID of the group in the source. If this is the same ID as a group in the IdP, a service account in that group will implicitly be a part of this group as well. Can not be used together with ‘members’.
capabilities (list[Capability] | None) – List of capabilities (acls) this group should grant its users.
attributes (GroupAttributes | None) – Attributes of the group, this scopes down access based on the attributes specified.
metadata (dict[str, str] | None) – Custom, immutable application specific metadata. String key -> String value. Limits: Key are at most 32 bytes. Values are at most 512 bytes. Up to 16 key-value pairs. Total size is at most 4096.
members (Literal['allUserAccounts'] | list[str] | None) – Specifies which users are members of the group. Can not be used together with ‘source_id’.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]

class cognite.client.data_classes.iam.GroupList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: WriteableCogniteResourceList[GroupWrite, Group], NameTransformerMixin, InternalIdTransformerMixin

as_write() → GroupWriteList: Returns a writing version of this group list.

to_pandas( camel_case: bool = False, expand_metadata: bool = False, metadata_prefix: str = 'metadata.', convert_timestamps: bool = True, ) → pd.DataFrame

Convert the instance into a pandas DataFrame. Note that if the metadata column is expanded and there are keys in the metadata that already exist in the DataFrame, then an error will be raised by pd.join.

Parameters:

camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
expand_metadata (bool) – Expand the metadata column into separate columns.
metadata_prefix (str) – Prefix to use for metadata columns.
convert_timestamps (bool) – Convert known columns storing CDF timestamps (milliseconds since epoch) to datetime. Does not affect custom data like metadata.

Returns:

The Cognite resource as a dataframe.

Return type:

pandas.DataFrame

Bases: GroupCore

Groups are used to give principals the capabilities to access CDF resources. One principal can be a member in multiple groups and one group can have multiple members.

Groups can either be managed through the external identity provider for the project or managed by CDF.

Parameters:

name (str) – Name of the group.
source_id (str | None) – ID of the group in the source. If this is the same ID as a group in the IdP, a service account in that group will implicitly be a part of this group as well. Can not be used together with ‘members’.
capabilities (list[Capability] | None) – List of capabilities (acls) this group should grant its users.
attributes (GroupAttributes | None) – Attributes of the group, this scopes down access based on the attributes specified.
metadata (dict[str, str] | None) – Custom, immutable application specific metadata. String key -> String value. Limits: Key are at most 32 bytes. Values are at most 512 bytes. Up to 16 key-value pairs. Total size is at most 4096.
members (Literal['allUserAccounts'] | list[str] | None) – Specifies which users are members of the group. Can not be used together with ‘source_id’.

as_write() → GroupWrite: Returns this GroupWrite instance.

class cognite.client.data_classes.iam.GroupWriteList( resources: Iterable[Any], cognite_client: CogniteClient | None = None, ): Bases: CogniteResourceList[GroupWrite], NameTransformerMixin

class cognite.client.data_classes.iam.ProjectSpec(url_name: str, groups: list[int])

Bases: CogniteResponse

A CDF project spec

Parameters:

url_name (str) – The url name for the project
groups (list[int]) – Group ids in the project

dump(camel_case: bool = True) → dict[str, str | list[int]]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]

class cognite.client.data_classes.iam.SecurityCategory( name: str | None = None, id: int | None = None, cognite_client: CogniteClient | None = None, )

Bases: SecurityCategoryCore

Security categories can be used to restrict access to a resource. This is the reading version of a security category, which is used when retrieving security categories.

Parameters:

name (str | None) – Name of the security category
id (int | None) – Id of the security category
cognite_client (CogniteClient | None) – The client to associate with this object.

as_write() → SecurityCategoryWrite: Returns a writing version of this security category.

class cognite.client.data_classes.iam.SecurityCategoryCore(name: str | None = None)

Bases: WriteableCogniteResource[SecurityCategoryWrite], ABC

No description.

Parameters:: name (str | None) – Name of the security category

class cognite.client.data_classes.iam.SecurityCategoryList( resources: Iterable[Any], cognite_client: CogniteClient | None = None, )

Bases: WriteableCogniteResourceList[SecurityCategoryWrite, SecurityCategory], InternalIdTransformerMixin, NameTransformerMixin

as_write() → SecurityCategoryWriteList: Returns a writing version of this security category list.

class cognite.client.data_classes.iam.SecurityCategoryWrite(name: str)

Bases: SecurityCategoryCore

Security categories can be used to restrict access to a resource. This is the writing version of a security category, which is used when creating security categories.

Parameters:: name (str) – Name of the security category

as_write() → SecurityCategoryWrite: Returns this SecurityCategoryWrite instance.

class cognite.client.data_classes.iam.SecurityCategoryWriteList( resources: Iterable[Any], cognite_client: CogniteClient | None = None, ): Bases: CogniteResourceList[SecurityCategoryWrite], NameTransformerMixin

Bases: CogniteResource

Session status

Parameters:

id (int | None) – ID of the session.
type (SessionType | None) – Credentials kind used to create the session.
status (SessionStatus | None) – Current status of the session.
creation_time (int | None) – Session creation time, in milliseconds since 1970
expiration_time (int | None) – Session expiry time, in milliseconds since 1970. This value is updated on refreshing a token
client_id (str | None) – Client ID in identity provider. Returned only if the session was created using client credentials
cognite_client (CogniteClient | None) – No description.

class cognite.client.data_classes.iam.SessionList( resources: Iterable[Any], cognite_client: CogniteClient | None = None, ): Bases: CogniteResourceList[Session], IdTransformerMixin

class cognite.client.data_classes.iam.TokenInspection( subject: str, projects: list[ProjectSpec], capabilities: ProjectCapabilityList, )

Bases: CogniteResponse

Current login status

Parameters:

subject (str) – Subject (sub claim) of JWT.
projects (list[ProjectSpec]) – Projects this token is valid for.
capabilities (ProjectCapabilityList) – Capabilities associated with this token.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]

class cognite.client.data_classes.user_profiles.UserProfile( user_identifier: str, last_updated_time: int, given_name: str | None = None, surname: str | None = None, email: str | None = None, display_name: str | None = None, job_title: str | None = None, cognite_client: CogniteClient | None = None, )

Bases: CogniteResource

User profiles is an authoritative source of core user profile information (email, name, job title, etc.) for principals based on data from the identity provider configured for the CDF project.

Parameters:

user_identifier (str) – Uniquely identifies the principal the profile is associated with. This property is guaranteed to be immutable.
last_updated_time (int) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
given_name (str | None) – The user’s first name.
surname (str | None) – The user’s last name.
email (str | None) – The user’s email address (if any). The email address is is returned directly from the identity provider and not guaranteed to be verified. Note that the email is mutable and can be updated in the identity provider. It should not be used to uniquely identify as a user. Use the user_identifier property instead.
display_name (str | None) – The display name for the user.
job_title (str | None) – The user’s job title.
cognite_client (CogniteClient | None) – No description.

class cognite.client.data_classes.user_profiles.UserProfileList( resources: Sequence[UserProfile], cognite_client: CogniteClient | None = None, )

Bases: CogniteResourceList[UserProfile]

get( user_identifier: str, ) → UserProfile | None

Get an item from this list by user_identifier. :param user_identifier: The user_identifier of the item to get. :type user_identifier: str

Returns:: The requested item or None if not found.
Return type:: UserProfile | None

class cognite.client.data_classes.user_profiles.UserProfilesConfiguration(enabled: bool): Bases: CogniteResource

class cognite.client.data_classes.principals.Principal(id: str)

Bases: CogniteResource, ABC

dump(camel_case: bool = True) → dict[str, Any]: Dump the principal to a dictionary.

class cognite.client.data_classes.principals.PrincipalList( resources: Iterable[Any], cognite_client: CogniteClient | None = None, )

Bases: CogniteResourceList[Principal]

as_ids() → list[str]: Returns a list of principal IDs.

class cognite.client.data_classes.principals.ServiceAccountCreator(org_id: str, user_id: str)

Bases: CogniteObject

The creator of a service account.

Parameters:

org_id (str) – The ID of an organization.
user_id (str) – The ID of an organization user

class cognite.client.data_classes.principals.ServicePrincipal( id: str, name: str, created_by: ServiceAccountCreator, created_time: int, last_updated_time: int, picture_url: str, external_id: str | None = None, description: str | None = None, )

Bases: Principal

Represents a service account principal in Cognite Data Fusion (CDF).

Parameters:

id (str) – Unique identifier of a service account
name (str) – Human-readable name of the service account
created_by (ServiceAccountCreator) – The creator of the service account
created_time (int) – When the principal was created. It is given as the number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
last_updated_time (int) – When the principal was last updated. It is given as the number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
picture_url (str) – URL to a picture of the principal.
external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.
description (str | None) – A description of the service account.

dump(camel_case: bool = True) → dict[str, Any]: Dump the principal to a dictionary.

class cognite.client.data_classes.principals.UnknownPrincipal(id: str, type: str, data: dict[str, Any])

Bases: Principal

Represents an unknown principal in Cognite Data Fusion (CDF).

This class is used when the principal type is not recognized or not defined in the SDK. Typically, this can happen when a new type of principal is introduced in CDF that is not yet supported by the SDK.

Parameters:

id (str) – Unique identifier of the principal.
type (str) – The type of the principal, which is not recognized by the SDK.
data (dict[str, Any]) – Additional data associated with the principal, excluding the ‘id’ and ‘type’ fields.

dump(camel_case: bool = True) → dict[str, Any]: Dump the principal to a dictionary.

class cognite.client.data_classes.principals.UserPrincipal( id: str, name: str, picture_url: str, email: str | None = None, given_name: str | None = None, middle_name: str | None = None, family_name: str | None = None, )

Bases: Principal

Represents a user principal in Cognite Data Fusion (CDF).

Parameters:

id (str) – The ID of an organization user
name (str) – Human-readable name of the principal
picture_url (str) – URL to a picture of the principal
email (str | None) – User email. Do not use this to uniquely identify a user, as it can be changed and is not guaranteed to be unique. Use the id field instead.
given_name (str | None) – The given name of the user
middle_name (str | None) – The middle name of the user
family_name (str | None) – The family name of the user