Principal is an umbrella term for user accounts and service accounts. Both entities can be uniquely identified, authenticated, and authorized in CDF. Principals are unique within an organization, and therefore also within a project in the organization. Principals can access data and create and run processes (transformations, Functions) in a CDF project.
Requests to the Principals API are directed to auth.cognite.com, like for organizations.
Only OAuth tokens issued by https://auth.cognite.com (such as the ones issued when logging into Fusion) are accepted
by the Principals API.
It is also possible to obtain a token by initiating a login flow against the authorization server directly. See the "Authorizations" sections for more information.
The Principals API lets you query user accounts in an organization, and retrieve profiles.
Retrieves the information of the principal issuing the request.
This endpoint is useful for clients to verify their own identity. All authenticated principals can call this endpoint.
The principal that issued the request.
{- "id": "5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT",
- "type": "SERVICE_ACCOUNT",
- "externalId": "my.known.id",
- "name": "My service account",
- "description": "This is a service account used by data pipeline A-xxx",
- "createdBy": {
- "orgId": "my-org",
- "userId": "-user-string-id-aBc123"
}, - "createdTime": 1730204346000,
- "lastUpdatedTime": 1730204346000,
- "pictureUrl": "string"
}List principals in an organization.
All principal types are supported.
Requires the caller to be logged into the target organization, or to be an admin in any of its the ancestor organizations.
A list of principals, with a cursor pointing to the next results page (if any).
{- "items": [
- {
- "id": "5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT",
- "type": "SERVICE_ACCOUNT",
- "externalId": "my.known.id",
- "name": "string",
- "description": "This is a service account used by data pipeline A-xxx",
- "createdBy": {
- "orgId": "my-org",
- "userId": "-user-string-id-aBc123"
}, - "createdTime": 1730204346000,
- "lastUpdatedTime": 1730204346000,
- "pictureUrl": "string"
}
], - "nextCursor": {
- "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
}
}Retrieve principals in an organization by ID or external ID.
Service accounts can be retrieved by ID or external ID. Users can be retrieved by ID.
Requires the caller to be logged into the target organization, or to be an admin in any of its the ancestor organizations.
A request to retrieve principals by reference.
For now, only service accounts can have an external ID.
A list of principals.
{- "items": [
- {
- "id": "5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT"
}
], - "ignoreUnknownIds": false
}{- "items": [
- {
- "id": "5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT",
- "type": "SERVICE_ACCOUNT",
- "externalId": "my.known.id",
- "name": "string",
- "description": "This is a service account used by data pipeline A-xxx",
- "createdBy": {
- "orgId": "my-org",
- "userId": "-user-string-id-aBc123"
}, - "createdTime": 1730204346000,
- "lastUpdatedTime": 1730204346000,
- "pictureUrl": "string"
}
]
}List login sessions for a user principal in an organization.
Note that a login session is what a user gets after logging into Fusion, InField, or another Cognite application. It is distinct from the concept of the "sessions" that can be used for background work like Transformations or Functions; however, each such background session is backed by a login session.
This endpoint does not work for service account principals, which do not have login sessions.
Requires the caller to be an admin of the target organization (it is not sufficient to be an admin of an ancestor organization).
A list of login sessions, with a cursor pointing to the next results page (if any).
Bad parameters: the limit is out of range or not a number, or the cursor is invalid.
The calling user is not an admin of the organization, or the principal id references a service account rather than a user.
The principal id does not exist, or does not belong to this organization.
{- "items": [
- {
- "id": "aea91e72-a984-4a4c-ba06-a7f54e650825",
- "createdTime": 0,
- "status": "ACTIVE",
- "deactivatedTime": 0
}
], - "nextCursor": {
- "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
}
}Revoke one or more login sessions for a user principal in an organization.
Note that a login session is what a user gets after logging into Fusion, InField, or another Cognite application. It is distinct from the concept of the "sessions" that can be used for background work like Transformations or Functions; however, each such background session is backed by a login session.
Upon successful completion of a login flow, the user receives an access token and a refresh token, which are both associated with the newly established login session. (Note that the user may have multiple concurrent login sessions.) The user may use the access token to send requests to the Cognite API, and the refresh token to obtain a new access token before the current one expires. Refreshing will also produce a new refresh token and invalidate the previous one. Every access token and refresh token in this "chain" is associated with the same login session.
Revoking a login session will set its status to REVOKED (which will be reflected in
/api/v1/orgs/{org}/principals/{principal}/sessions), which within a short amount of time will prevent the user
from accessing the Cognite systems via that login session. Specifically:
Note that the user may still have other active login sessions, which will remain active. If you want to
completely prevent a user from accessing Cognite systems, you should remove them from your organization's
external identity provider (e.g. your Entra ID tenant), which will prevent them from logging in again, and then
call /api/v1/orgs/{org}/principals/{principal}/sessions to list all their current login sessions and then pass
all their ids to this endpoint (in batches, if there are more than 10) to revoke them.
Also note that because the REVOKED status is "stronger" than the LOGGED_OUT status (background sessions
remain active in the latter status but not in the former), it is possible to revoke a login session that is
LOGGED_OUT (which will stop any associated background sessions). Currently, REVOKED has the same
consequences as EXPIRED, but revocation might be expanded in the future to become even stronger, so it is also
possible to revoke a login session that is EXPIRED. Revoking a login session that is already REVOKED will
succeed but will have no effect (in particular, the deactivatedTime of the login session will not change).
This endpoint is atomic: if revocation of any of the given login sessions fails, none of the login sessions will be revoked. In other words, any other status code than 204 means that no login sessions were revoked.
This endpoint does not work for service account principals, which do not have login sessions.
Requires the caller to be an admin of the target organization (it is not sufficient to be an admin of an ancestor organization).
A request to revoke login sessions for a user principal.
required | Array of objects [ 1 .. 10 ] items |
Login sessions revoked successfully.
Bad request body: the number of login sessions to revoke is out of range, or one or more of the login session ids do not exist or do not belong to this organization or user principal.
The calling user is not an admin of the organization, or the principal id references a service account rather than a user.
The principal id does not exist, or does not belong to this organization.
{- "items": [
- {
- "id": "aea91e72-a984-4a4c-ba06-a7f54e650825"
}
]
}{- "code": 0,
- "message": "string"
}