Identity and access management

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
>>> c = CogniteClient()
>>> res = c.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 groups:

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

Create groups

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

Create one or more groups.

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

Example

Create group:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import Group
>>> c = CogniteClient()
>>> my_capabilities = [{"groupsAcl": {"actions": ["LIST"],"scope": {"all": { }}}}]
>>> my_group = Group(name="My Group", capabilities=my_capabilities)
>>> res = c.iam.groups.create(my_group)

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
>>> c = CogniteClient()
>>> c.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
>>> c = CogniteClient()
>>> res = c.iam.security_categories.list()

Create security categories

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

Create one or more security categories.

Parameters: security_category (SecurityCategory | Sequence[SecurityCategory]) – 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 SecurityCategory
>>> c = CogniteClient()
>>> my_category = SecurityCategory(name="My Category")
>>> res = c.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
>>> c = CogniteClient()
>>> c.iam.security_categories.delete(1)

Sessions

List sessions

SessionsAPI.list(status: str | None = None) → SessionList

List all sessions in the current project.

Parameters: status (str | None) – If given, only sessions with the given status are returned.
Returns: a list of sessions in the current project.
Return type: SessionList

Create a session

SessionsAPI.create(client_credentials: ClientCredentials | None = None) → CreatedSession

Create a session.

Parameters: client_credentials (ClientCredentials | None) – The client credentials to create the session. If set to None, a session will be created using the credentials used to instantiate -this- CogniteClient object. If that was done using a token, a session will be created using token exchange. Similarly, if the credentials were client credentials, a session will be created using client credentials. This method does not work when using client certificates (not supported server-side).
Returns: The object with token inspection details.
Return type: CreatedSession

Revoke a session

SessionsAPI.revoke(id: int | Sequence[int]) → 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: SessionList

User Profiles

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
>>> c = CogniteClient()
>>> res = c.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
>>> c = CogniteClient()
>>> res = c.iam.user_profiles.list(limit=None)

Retrieve one or more user profiles

UserProfilesAPI.retrieve(user_identifier: str) → UserProfile | None

UserProfilesAPI.retrieve(user_identifier: MutableSequence[str] | tuple[str, ...]) → UserProfileList

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 | MutableSequence[str] | tuple[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
>>> c = CogniteClient()
>>> res = c.iam.user_profiles.retrieve("foo")

Get multiple user profiles:

>>> res = c.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
>>> c = CogniteClient()
>>> res = c.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.

class cognite.client.data_classes.iam.CreatedSession(id: int, status: str, nonce: str, type: str | None = None, client_id: str | None = None)

Bases: CogniteResponse

Session creation related information

Parameters

id (int) – ID of the created session.
status (str) – Current status of the session.
nonce (str) – Nonce to be passed to the internal service that will bind the session
type (str | 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: CogniteResource

No description.

Parameters

name (str | None) – 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.
capabilities (list[dict[str, Any]] | None) – No description.
id (int | None) – No description.
is_deleted (bool | None) – No description.
deleted_time (int | None) – No description.
metadata (dict[str, Any] | None) – Custom, immutable application specific metadata. String key -> String value. Limits:
cognite_client (CogniteClient | None) – The client to associate with this object.

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

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

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

Bases: CogniteResource

No description.

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.

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

Bases: CogniteResource

Session status

Parameters

id (int | None) – ID of the session.
type (str | None) – Credentials kind used to create the session.
status (str | 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: Collection[Any], cognite_client: CogniteClient | None = None): Bases: CogniteResourceList[Session]

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

Bases: CogniteResponse

Current login status

Parameters

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

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

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to False.
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