Identity and access management

Compare access rights (capabilities)

AsyncCogniteClient.iam.compare_capabilities(...)

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

AsyncCogniteClient.iam.verify_capabilities(...)

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

Principals

AsyncCogniteClient.iam.principals.list([...])

List principals in the organization.

AsyncCogniteClient.iam.principals.me()

Get the current caller's information.

AsyncCogniteClient.iam.principals.retrieve([...])

Retrieve principal by reference in the organization.

Tokens

AsyncCogniteClient.iam.token.inspect()

Inspect a token.

Groups

AsyncCogniteClient.iam.groups.create(group)

Create one or more groups.

AsyncCogniteClient.iam.groups.delete(id)

Delete one or more groups.

AsyncCogniteClient.iam.groups.list([all])

List groups.

Security categories

AsyncCogniteClient.iam.security_categories.create(...)

Create one or more security categories.

AsyncCogniteClient.iam.security_categories.delete(id)

Delete one or more security categories.

AsyncCogniteClient.iam.security_categories.list([...])

List security categories.

Sessions

AsyncCogniteClient.iam.sessions.create([...])

Create a session.

AsyncCogniteClient.iam.sessions.list([...])

List all sessions in the current project.

AsyncCogniteClient.iam.sessions.retrieve(id)

Retrieves sessions with given IDs.

AsyncCogniteClient.iam.sessions.revoke(id)

Revoke access to a session.

User Profiles

AsyncCogniteClient.iam.user_profiles.disable()

Disable user profiles for the project

AsyncCogniteClient.iam.user_profiles.enable()

Enable user profiles for the project

AsyncCogniteClient.iam.user_profiles.list([limit])

List user profiles.

AsyncCogniteClient.iam.user_profiles.me()

Retrieve your own user profile

AsyncCogniteClient.iam.user_profiles.retrieve(...)

Retrieve user profiles by user identifier.

AsyncCogniteClient.iam.user_profiles.search(name)

Search for user profiles.

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.

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: CogniteResource

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

class cognite.client.data_classes.iam.Group(
id: int,
name: str,
is_deleted: bool,
source_id: str | None = None,
capabilities: list[Capability] | Capability | None = None,
attributes: GroupAttributes | None = None,
deleted_time: int | None = None,
metadata: dict[str, str] | None = None,
members: Literal['allUserAccounts'] | list[str] | None = None,
)

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:

  • id (int) – No description.

  • name (str) – Name of the group.

  • is_deleted (bool) – No description.

  • 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] | 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.

  • 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’.

as_write() → GroupWrite

Returns a write 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: CogniteResource

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: CogniteResource

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

class cognite.client.data_classes.iam.GroupCore(
name: str,
source_id: str | None,
capabilities: list[Capability] | Capability | None,
attributes: GroupAttributes | None,
metadata: dict[str, str] | None,
members: Literal['allUserAccounts'] | list[str] | None,
)

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] | 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: Sequence[T_CogniteResource],
)

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

as_write() → GroupWriteList

Returns a write 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

class cognite.client.data_classes.iam.GroupWrite(
name: str,
source_id: str | None = None,
capabilities: list[Capability] | None = None,
attributes: GroupAttributes | None = None,
metadata: dict[str, str] | None = None,
members: Literal['allUserAccounts'] | list[str] | None = None,
)

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: Sequence[T_CogniteResource],
)

Bases: CogniteResourceList[GroupWrite], NameTransformerMixin

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

Bases: CogniteResource

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(id: int, name: str)

Bases: SecurityCategoryCore

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

Parameters:

  • id (int) – Id of the security category

  • name (str) – Name of the security category

as_write() → SecurityCategoryWrite

Returns a write version of this security category.

class cognite.client.data_classes.iam.SecurityCategoryCore(name: str)

Bases: WriteableCogniteResource[SecurityCategoryWrite], ABC

No description.

Parameters:

name (str) – Name of the security category

class cognite.client.data_classes.iam.SecurityCategoryList(
resources: Sequence[T_CogniteResource],
)

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

as_write() → SecurityCategoryWriteList

Returns a write 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 write 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: Sequence[T_CogniteResource],
)

Bases: CogniteResourceList[SecurityCategoryWrite], NameTransformerMixin

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

Bases: CogniteResource

Session status

Parameters:

  • id (int) – ID of the session.

  • type (SessionType) – Credentials kind used to create the session.

  • status (SessionStatus) – Current status of the session.

  • creation_time (int) – Session creation time, in milliseconds since 1970

  • expiration_time (int) – 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

class cognite.client.data_classes.iam.SessionList(
resources: Sequence[T_CogniteResource],
)

Bases: CogniteResourceList[Session], IdTransformerMixin

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

Bases: CogniteResource

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,
)

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.

class cognite.client.data_classes.user_profiles.UserProfileList(
resources: Sequence[T_CogniteResource],
)

Bases: CogniteResourceList[UserProfile]

extend(other: Iterable[Any]) → None

S.extend(iterable) – extend sequence by appending elements from the iterable

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: Sequence[T_CogniteResource],
)

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: CogniteResource

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