Identity and access management
Compare access rights (capabilities)
Verify my capabilities
- IAMAPI.verify_capabilities(desired_capabilities: ComparableCapability, ignore_allscope_meaning: bool = False) list[Capability]
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
- static IAMAPI.compare_capabilities(existing_capabilities: ComparableCapability, desired_capabilities: ComparableCapability, project: str | None = None, ignore_allscope_meaning: bool = False) list[Capability]
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.
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
Example
Inspect token:
>>> from cognite.client import CogniteClient >>> client = CogniteClient() >>> res = client.iam.token.inspect()
Groups
List groups
- GroupsAPI.list(all: bool = False) GroupList
-
- Parameters
all (bool) – Whether to get all groups, only available with the groups:list acl.
- Returns
List of groups.
- Return type
Example
List your own groups:
>>> from cognite.client import CogniteClient >>> client = CogniteClient() >>> res = client.iam.groups.list()
List all groups:
>>> res = client.iam.groups.list(all=True)
Create groups
- GroupsAPI.create(group: Group | GroupWrite) Group
- GroupsAPI.create(group: Sequence[Group] | Sequence[GroupWrite]) GroupList
-
- Parameters
group (Group | GroupWrite | Sequence[Group] | Sequence[GroupWrite]) – Group or list of groups to create.
- Returns
The created group(s).
- Return type
Example
Create group:
>>> 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)
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)
Security categories
List security categories
- SecurityCategoriesAPI.list(limit: int | None = 25) SecurityCategoryList
-
- 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
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) SecurityCategory
- SecurityCategoriesAPI.create(security_category: Sequence[SecurityCategory] | Sequence[SecurityCategoryWrite]) 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
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: SessionStatus | 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
Create a session
- SessionsAPI.create(client_credentials: ClientCredentials | None = None) CreatedSession
-
- 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
Retrieve a session
- SessionsAPI.retrieve(id: int) Session
- SessionsAPI.retrieve(id: Sequence[int]) 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
Revoke a session
- SessionsAPI.revoke(id: int) Session
- SessionsAPI.revoke(id: Sequence[int]) SessionList
-
- 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
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
- 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 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
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) UserProfile | None
- UserProfilesAPI.retrieve(user_identifier: SequenceNotStr[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 | 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
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: SessionStatus, nonce: str, type: SessionType | 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
- class cognite.client.data_classes.iam.Group(name: str, source_id: str | None = None, capabilities: list[Capability] | None = None, id: int | None = None, is_deleted: bool | None = None, deleted_time: int | None = None, metadata: dict[str, Any] | None = None, cognite_client: CogniteClient | None = None)
Bases:
GroupCore
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.
capabilities (list[Capability] | None) – List of capabilities (acls) this group should grant its users.
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: Key are at most 32 bytes. Values are at most 512 bytes. Up to 16 key-value pairs. Total size is at most 4096.
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.GroupCore(name: str, source_id: str | None = None, capabilities: list[Capability] | None = None, metadata: dict[str, Any] | None = 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.
capabilities (list[Capability] | None) – List of capabilities (acls) this group should grant its users.
metadata (dict[str, Any] | 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.
- 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: Collection[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
- class cognite.client.data_classes.iam.GroupWrite(name: str, source_id: str | None = None, capabilities: list[Capability] | None = None, metadata: dict[str, Any] | None = None)
Bases:
GroupCore
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.
capabilities (list[Capability] | None) – List of capabilities (acls) this group should grant its users.
metadata (dict[str, Any] | 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.
- as_write() GroupWrite
Returns this GroupWrite instance.
- class cognite.client.data_classes.iam.GroupWriteList(resources: Collection[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: Collection[Any], cognite_client: CogniteClient | None = None)
Bases:
WriteableCogniteResourceList
[SecurityCategoryWrite
,SecurityCategory
],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: Collection[Any], cognite_client: CogniteClient | None = None)
Bases:
CogniteResourceList
[SecurityCategoryWrite
],NameTransformerMixin
- class cognite.client.data_classes.iam.Session(id: int | None = None, type: SessionType | None = None, status: SessionStatus | None = None, creation_time: int | None = None, expiration_time: int | None = None, client_id: str | None = None, cognite_client: CogniteClient | None = None)
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: Collection[Any], cognite_client: CogniteClient | None = None)
Bases:
CogniteResourceList
[Session
]
- 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