Cognite Principals API

openapi: 3.2.0
info:
  title: Cognite Principals API
  description: '# Introduction

    This is the reference documentation for the Cognite API with

    an overview of all the available methods.'
  version: v1
  contact:
    name: Cognite Support
    url: https://support.cognite.com
    email: support@cognite.com
servers:
- url: https://{cluster}.cognitedata.com/api/v1/projects/{project}
  description: The URL for the CDF cluster to connect to
  variables:
    cluster:
      enum:
      - api
      - az-tyo-gp-001
      - az-eastus-1
      - az-power-no-northeurope
      - westeurope-1
      - asia-northeast1-1
      - gc-dsm-gp-001
      default: api
      description: The CDF cluster to connect to
    project:
      default: publicdata
      description: The CDF project name.
security:
- oidc-token:
  - https://{cluster}.cognitedata.com/.default
- oauth2-client-credentials:
  - https://{cluster}.cognitedata.com/.default
- oauth2-open-industrial-data:
  - https://api.cognitedata.com/.default
- oauth2-auth-code:
  - https://{cluster}.cognitedata.com/.default
tags:
- name: Principals
  description: '**Principal** is an umbrella term for **user accounts** and **service accounts**.'
paths:
  /api/v1/principals/me:
    servers:
    - url: https://auth.cognite.com
    get:
      operationId: getMe
      summary: Get the current caller's information
      security:
      - org-oidc-token: []
      description: '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.'
      tags:
      - Principals
      responses:
        '200':
          $ref: '#/components/responses/MeResponse'
  /api/v1/orgs/{org}/principals:
    servers:
    - url: https://auth.cognite.com
    get:
      operationId: listPrincipals
      summary: List principals
      security:
      - org-oidc-token: []
      description: 'List principals in an organization.


        All principal types are supported.


        #### Access control

        Requires the caller to be logged into the target organization, or

        to be an admin in any of its the ancestor organizations.'
      tags:
      - Principals
      parameters:
      - $ref: '#/components/parameters/OrgId'
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/ListLimit100'
      - $ref: '#/components/parameters/PrincipalTypes'
      responses:
        '200':
          $ref: '#/components/responses/PrincipalsPaginatedListResponse'
  /api/v1/orgs/{org}/principals/byids:
    servers:
    - url: https://auth.cognite.com
    post:
      operationId: getPrincipalsById
      summary: Retrieve principals by reference
      security:
      - org-oidc-token: []
      description: '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.


        #### Access control

        Requires the caller to be logged into the target organization, or

        to be an admin in any of its the ancestor organizations.'
      tags:
      - Principals
      parameters:
      - $ref: '#/components/parameters/OrgId'
      requestBody:
        $ref: '#/components/requestBodies/PrincipalsListByIdsRequest'
      responses:
        '200':
          $ref: '#/components/responses/PrincipalsListResponse'
  /api/v1/orgs/{org}/principals/{principal}/sessions:
    servers:
    - url: https://auth.cognite.com
    get:
      operationId: listLoginSessionsForUserPrincipal
      summary: List login sessions
      security:
      - org-oidc-token: []
      description: '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.


        #### Access control

        Requires the caller to be an admin of the target organization (it is not sufficient to be an admin of an

        ancestor organization).'
      tags:
      - Principals
      parameters:
      - $ref: '#/components/parameters/OrgId'
      - $ref: '#/components/parameters/PrincipalId'
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/ListLimit1000'
      responses:
        '200':
          $ref: '#/components/responses/LoginSessionsPaginatedListResponse'
        '400':
          $ref: '#/components/responses/LoginSessionsListBadRequestResponse'
        '403':
          $ref: '#/components/responses/LoginSessionsForbiddenResponse'
        '404':
          $ref: '#/components/responses/LoginSessionsNotFoundResponse'
  /api/v1/orgs/{org}/principals/{principal}/sessions/revoke:
    servers:
    - url: https://auth.cognite.com
    post:
      operationId: revokeLoginSessionsForUserPrincipal
      summary: Revoke login sessions
      security:
      - org-oidc-token: []
      description: '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:

        - Requests to the Cognite API that use any access token that is associated with this session will be rejected.

        - Requests to refresh the login session will be rejected.

        - Background jobs that were started from this login session will stop working. Note that this might take up to

        one hour to take effect.


        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.


        #### Access control

        Requires the caller to be an admin of the target organization (it is not sufficient to be an admin of an

        ancestor organization).'
      tags:
      - Principals
      parameters:
      - $ref: '#/components/parameters/OrgId'
      - $ref: '#/components/parameters/PrincipalId'
      requestBody:
        $ref: '#/components/requestBodies/RevokeLoginSessionsRequest'
      responses:
        '204':
          description: Login sessions revoked successfully.
        '400':
          $ref: '#/components/responses/LoginSessionsRevokeBadRequestResponse'
        '403':
          $ref: '#/components/responses/LoginSessionsForbiddenResponse'
        '404':
          $ref: '#/components/responses/LoginSessionsNotFoundResponse'
components:
  responses:
    LoginSessionsRevokeBadRequestResponse:
      description: '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.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
    MeResponse:
      description: The principal that issued the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrincipalDto'
    LoginSessionsNotFoundResponse:
      description: The principal id does not exist, or does not belong to this organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
    LoginSessionsListBadRequestResponse:
      description: 'Bad parameters: the limit is out of range or not a number, or the cursor is invalid.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
    PrincipalsPaginatedListResponse:
      description: A list of principals, with a cursor pointing to the next results page (if any).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrincipalsListPaginatedDto'
    LoginSessionsPaginatedListResponse:
      description: A list of login sessions, with a cursor pointing to the next results page (if any).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LoginSessionsListPaginatedDto'
    PrincipalsListResponse:
      description: A list of principals.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrincipalsListResponseDto'
    LoginSessionsForbiddenResponse:
      description: 'The calling user is not an admin of the organization, or the principal id references a service account rather

        than a user.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
  schemas:
    ReferenceByIdOrExternalId:
      type: object
      description: Either a principal ID, or a principal external ID
      oneOf:
      - $ref: '#/components/schemas/ReferenceById'
      - $ref: '#/components/schemas/ReferenceByExternalId'
    UserId:
      type: string
      description: The ID of an organization user
      minLength: 22
      maxLength: 22
      example: -user-string-id-aBc123
      pattern: ^[-_a-zA-Z0-9]{22}$
    BasePrincipalDto:
      type: object
      description: A principal
      required:
      - id
      - name
      - pictureUrl
      properties:
        id:
          $ref: '#/components/schemas/PrincipalId'
        name:
          $ref: '#/components/schemas/PrincipalName'
        pictureUrl:
          $ref: '#/components/schemas/PrincipalPictureUrl'
    PrincipalId:
      type: string
      description: Unique identifier of a principal
      example: 5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT
    EpochTimestamp:
      description: The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
      type: integer
      minimum: 0
      format: int64
      example: 1730204346000
    ServiceAccountDescription:
      type: string
      description: Longer description of a service account
      maxLength: 500
      example: This is a service account used by data pipeline A-xxx
    CogniteExternalId:
      description: The external ID provided by the client. Must be unique for the resource type.
      type: string
      maxLength: 255
      example: my.known.id
    ReferenceByExternalId:
      type: object
      required:
      - externalId
      properties:
        externalId:
          $ref: '#/components/schemas/CogniteExternalId'
    SimpleError:
      type: object
      required:
      - code
      - message
      description: Cognite API error.
      properties:
        code:
          type: integer
          description: HTTP status code.
          format: int32
        message:
          type: string
          description: Error message.
    PrincipalDto:
      oneOf:
      - $ref: '#/components/schemas/ServiceAccountDto'
      - $ref: '#/components/schemas/UserDto'
    OrgId:
      type: string
      description: The ID of an organization
      minLength: 3
      maxLength: 64
      example: my-org
      pattern: ^([a-z][a-z0-9-]{1,62}[a-z0-9])$
    ServiceAccountName:
      type: string
      description: Human-readable name of a service account
      minLength: 1
      maxLength: 50
      example: My service account
    ServiceAccountCreatorUser:
      type: object
      description: The user that created the entity.
      required:
      - orgId
      - userId
      properties:
        orgId:
          $ref: '#/components/schemas/OrgId'
        userId:
          $ref: '#/components/schemas/UserId'
    ServiceAccountDto:
      allOf:
      - type: object
        description: A service account
        required:
        - id
        - type
        - name
        - createdBy
        - createdTime
        - lastUpdatedTime
        properties:
          id:
            $ref: '#/components/schemas/ServiceAccountId'
          type:
            type: string
            description: Principal type
            enum:
            - SERVICE_ACCOUNT
            example: SERVICE_ACCOUNT
          externalId:
            $ref: '#/components/schemas/CogniteExternalId'
          name:
            $ref: '#/components/schemas/ServiceAccountName'
          description:
            $ref: '#/components/schemas/ServiceAccountDescription'
          createdBy:
            $ref: '#/components/schemas/ServiceAccountCreator'
          createdTime:
            $ref: '#/components/schemas/EpochTimestamp'
          lastUpdatedTime:
            $ref: '#/components/schemas/EpochTimestamp'
      - $ref: '#/components/schemas/BasePrincipalDto'
    ServiceAccountCreator:
      description: The principal that created the entity.
      oneOf:
      - $ref: '#/components/schemas/ServiceAccountCreatorUser'
    Cursor:
      type: object
      properties:
        cursor:
          type: string
          example: 4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo
      description: 'Cursor for paging through results. In general, if a response contains a `nextCursor`

        property, it means that there may be more results, and you should pass that value as the

        `cursor` parameter in the next request.


        Note that the cursor may or may not be encrypted, but either way, it is not intended to be

        decoded. Its internal structure is not a part of the public API, and may change without

        notice. You should treat it as an opaque string and not attempt to craft your own cursors.

        '
    LoginSessionsListPaginatedDto:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          maxLength: 100
          items:
            $ref: '#/components/schemas/LoginSessionDto'
        nextCursor:
          $ref: '#/components/schemas/Cursor'
    PrincipalType:
      type: string
      enum:
      - SERVICE_ACCOUNT
      - USER
      description: The type of a principal
    PrincipalListByIdsRequestDto:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/ReferenceByIdOrExternalId'
        ignoreUnknownIds:
          type: boolean
          default: false
          description: 'If `true`, IDs that do not match existing principals will be ignored.


            If `false`, the request will fail if any of the IDs do not match existing principals.

            This is the default behavior.'
    LoginSessionId:
      type: string
      description: Unique identifier of a login session.
      example: aea91e72-a984-4a4c-ba06-a7f54e650825
    ReferenceById:
      type: object
      required:
      - id
      properties:
        id:
          $ref: '#/components/schemas/PrincipalId'
    PrincipalsListResponseDto:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PrincipalDto'
    UserDto:
      allOf:
      - type: object
        description: A user
        required:
        - id
        - type
        - name
        properties:
          id:
            $ref: '#/components/schemas/UserId'
          type:
            type: string
            description: Principal type
            enum:
            - USER
            example: USER
          name:
            type: string
            example: John N. Doe
          email:
            type: string
            format: email
            description: '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.'
          givenName:
            type: string
            example: John
          middleName:
            type: string
            example: N.
          familyName:
            type: string
            example: Doe
      - $ref: '#/components/schemas/BasePrincipalDto'
    ServiceAccountId:
      type: string
      description: Unique identifier of a service account
      example: 5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT
    PrincipalPictureUrl:
      type: string
      description: URL to a picture of the principal
      format: url
    PrincipalsListPaginatedDto:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          maxLength: 100
          items:
            $ref: '#/components/schemas/PrincipalDto'
        nextCursor:
          $ref: '#/components/schemas/Cursor'
    PrincipalName:
      type: string
      description: Human-readable name of the principal
    LoginSessionDto:
      type: object
      required:
      - id
      - createdTime
      - status
      properties:
        id:
          $ref: '#/components/schemas/LoginSessionId'
        createdTime:
          type: integer
          description: The Unix timestamp (in milliseconds) when the login session was created (during the user's initial login).
        status:
          type: string
          description: "Login session status.\n\n- `ACTIVE`: The login session is active. The access token that was issued during login may be used to send\n  requests to the Cognite API, the refresh token may be used to obtain a new access token, and any\n  background jobs started from this login session will keep running.\n- `LOGGED_OUT`: The user logged themselves out. The access token that was issued during login may no longer\n  be used to send requests to the Cognite API, and the refresh token may no longer be used to obtain a new\n  access token. However, any background jobs started from this login session will keep running.\n- `EXPIRED`: Cognite failed to refresh the user's session in the organization's external identity provider\n  (the customer's Entra ID tenant or other identity provider service), and this login session is now\n  completely unusable. Like for `LOGGED_OUT`, the access and refresh tokens may no longer be used. Unlike\n  for `LOGGED_OUT`, any background jobs started from this login session will stop running.\n- `REVOKED`: The login session was revoked by an organization administrator via the\n  `/api/v1/orgs/{org}/principals/{principal}/sessions/revoke` endpoint, and this login session is now\n  completely unusable. Like for `EXPIRED`, the access and refresh tokens may no longer be used, and any\n  background jobs started from this login session will stop running."
          enum:
          - ACTIVE
          - LOGGED_OUT
          - EXPIRED
          - REVOKED
        deactivatedTime:
          type: integer
          description: 'The Unix timestamp (in milliseconds) when the login session was deactivated,

            or `null` or absent if `status` is `ACTIVE`.'
  parameters:
    PrincipalId:
      name: principal
      in: path
      description: ID of a principal
      required: true
      schema:
        $ref: '#/components/schemas/PrincipalId'
    Cursor:
      name: cursor
      description: 'Cursor for paging through results. In general, if a response contains a `nextCursor`

        property, it means that there may be more results, and you should pass that value as the

        `cursor` parameter in the next request.


        Note that the cursor may or may not be encrypted, but either way, it is not intended to be

        decoded. Its internal structure is not a part of the public API, and may change without

        notice. You should treat it as an opaque string and not attempt to craft your own cursors.

        '
      in: query
      schema:
        type: string
        example: 4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo
    OrgId:
      name: org
      in: path
      description: ID of an organization
      required: true
      schema:
        $ref: '#/components/schemas/OrgId'
    ListLimit1000:
      in: query
      required: false
      name: limit
      schema:
        type: integer
        minimum: 1
        maximum: 1000
      description: The maximum number of items to return.
    ListLimit100:
      in: query
      required: false
      name: limit
      schema:
        type: integer
        minimum: 1
        maximum: 100
    PrincipalTypes:
      in: query
      required: false
      name: types
      description: 'Filter by principal types.

        If not specified, all principal types will be included.

        You can filter by multiple types by providing a comma-separated list, or by repeating the parameter.'
      schema:
        $ref: '#/components/schemas/PrincipalType'
      example: USER,SERVICE_ACCOUNT
  requestBodies:
    RevokeLoginSessionsRequest:
      description: A request to revoke login sessions for a user principal.
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
            - items
            properties:
              items:
                type: array
                minItems: 1
                maxItems: 10
                items:
                  type: object
                  required:
                  - id
                  properties:
                    id:
                      $ref: '#/components/schemas/LoginSessionId'
    PrincipalsListByIdsRequest:
      description: 'A request to retrieve principals by reference.


        For now, only service accounts can have an external ID.'
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrincipalListByIdsRequestDto'
  securitySchemes:
    oidc-token:
      type: http
      scheme: bearer
      bearerFormat: OpenID Connect or OAuth2 token
      description: Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.
    oauth2-client-credentials:
      type: oauth2
      description: Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.
      flows:
        clientCredentials:
          tokenUrl: https://your-idps.token.url/
          scopes:
            default: https://{cluster}.cognitedata.com/.default
    oauth2-auth-code:
      type: oauth2
      description: Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.
      flows:
        authorizationCode:
          authorizationUrl: https://your-idps.authorization.url/
          tokenUrl: https://your-idps.token.url/
          scopes:
            default: https://{cluster}.cognitedata.com/.default
    oauth2-open-industrial-data:
      type: oauth2
      description: Auth flow for Open Industrial Data. Get your client secret from https://hub.cognite.com/open-industrial-data-211.
      flows:
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/48d5043c-cf70-4c49-881c-c638f5796997/oauth2/v2.0/token
          scopes:
            default: https://api.cognitedata.com/.default
    org-oidc-token:
      type: openIdConnect
      openIdConnectUrl: https://auth.cognite.com/.well-known/openid-configuration
      description: 'Access token issued by the Cognite authorization server, and valid for the target organization. The token must

        be an OpenID Connect token, and it can be obtained by performing an OIDC login flow toward `auth.cognite.com`.

        This is a single URL for all CDF organizations.'
x-tagGroups:
- name: Changelog
  tags:
  - Changelog
- name: Organizations and projects
  tags:
  - Organizations
  - Projects
- name: Identity and access management
  tags:
  - Principals
  - Groups
  - Security categories
  - Sessions
  - Token
  - User profiles
  - Project Deletion Reporting
- name: Data modeling
  tags:
  - Data Modeling
  - Data models
  - Spaces
  - Views
  - Containers
  - Nodes
  - Instances
  - Statistics
  - Streams
  - Records
- name: Asset-centric data model
  tags:
  - Assets
  - Time series
  - Synthetic Time Series
  - Data point subscriptions
  - Events
  - Files
  - Sequences
  - Geospatial
  - Seismic
- name: 3D
  tags:
  - 3D Models
  - 3D Model Revisions
  - 3D Files
  - 3D Asset Mapping
  - 3D Contextualization
  - 3D Jobs
  - 3D Migration
  - 3D Scenes
- name: Contextualization
  tags:
  - Entity matching
  - Entity matching pipelines
  - Engineering diagrams
  - Vision
  - Advanced joins
- name: Cognite AI
  tags:
  - Agents
  - Skills
  - Chat Completions
  - Document AI
  - Models
- name: Documents
  tags:
  - Documents
  - Document preview
- name: Data ingestion
  tags:
  - Raw
  - Extraction Pipelines
  - Extraction Pipelines Runs
  - Extraction Pipelines Config
  - Extractors
- name: Data organization
  tags:
  - Data sets
  - Data domains
  - Data products
  - Rule sets
  - Labels
  - Relationships
  - Annotations
- name: Transformations
  tags:
  - Transformations
  - Transformation Jobs
  - Transformation Schedules
  - Transformation Notifications
  - Query
  - Schema
- name: Functions
  tags:
  - Functions
  - Function calls
  - Function schedules
- name: Hosted Extractors
  tags:
  - Sources
  - Jobs
  - Destinations
  - Mappings
- name: PostgreSQL Gateway
  tags:
  - Postgres Gateway Users
  - Postgres Gateway Tables
- name: SAP Writeback
  tags:
  - SAP Instances
  - SAP Endpoints
  - Schema Mappings
  - Writeback Requests
- name: Data workflows
  tags:
  - Workflows
  - Workflow versions
  - Workflow executions
  - Workflow triggers
  - Tasks
  - Workers
- name: Simulators
  tags:
  - Simulators
  - Simulator Integrations
  - Simulator Models
  - Simulator Routines
  - Simulation Runs
  - Simulator Logs
- name: Units
  tags:
  - Units
  - Unit Systems
- name: ''
  tags:
  - ''