iTwins API

The iTwins API provides a full encompassing suite of functionality to manage your digital twins. With this API, you can create iTwins, control their lifecycle, discover repositories associated to them, query to get your recently used iTwins, and manage your favorite iTwins.


The iTwin is Bentley's digital twin object and the iTwins API is used to manage your iTwins. For non-technical information about managing your iTwins, please see Digital Twin Management in the Twin Platform documentation.

A digital twin exists in many shapes and sizes, or in engineering terms, many disciplines and phases. iTwins have properties to help describe the digital twin's purpose, which aligns with its discipline and phase. Specifically, an iTwin's class and subClass fields are used to specify its classification (e.g. Thing & Asset are used to classify an operating asset digital twin, while Endeavor & Project are used to classify a capital project digital twin). Use the iTwin's type field to further refine the iTwin's purpose. The iTwin's displayName and number fields are typical engineering properties for projects and assets, and can be used as such; Each of these fields are required to be unique for each subClass. Finally, modify the status property, with possible values of active, inactive, and trial to manage the lifecycle of the iTwin. The examples below show the use of these properties in engineering use-cases:

A digital twin of the US Route 202 highway

  "id": "051b685f-4168-4e2d-900e-49d57e171513",
  "class": "Thing",
  "subClass": "Asset",
  "type": "Highway",
  "displayName": "US Route 202",
  "number": "HWYUSR202",
  "status": "active"

A digital twin of a project to widen the 61N section of the US Route 202 highway

  "id": "01a5b73e-d5d3-47fc-ae3e-253365d93eb9",
  "class": "Endeavor",
  "subClass": "Project",
  "type": "Construction",
  "displayName": "US Route 202 Section 61N Expansion",
  "number": "HWYUSR202S61NEXP",
  "status": "active"

iTwin Access Control

Each and every iTwin implicitly contains built-in access control, managed using the Access Control API. The Access Control API follows Role Based Access Control security principles, which provides the capability to group permissions into roles and assign those roles to users on an iTwin. An iTwin role assignment gives you permissions on that iTwin and enables that functionality permitted by the permission. These permissions are required by many iTwin Platform services and you will see specific permission requirements documented in each service endpoint's Authorization section.

Access Control on iTwins gives you the capability to organize your iTwin's members working on your digital twins, which by way of the iTwin properties, is also aligned with the iTwin's purpose. Using different role assignments for different member personas allows you to manage your member's access control accordingly. Likewise, the Access Control API allows for external member invitations -- if someone outside of your organization is collaborating on your iTwin, simply invite them to your iTwin via a role assignment.

iTwin Repositories

Digital twins are all about the data, whether that be engineering modeling data, IoT sensor data, drone footage, 3d mesh drawings, or files and folders. The discovery of that data can be cumbersome and requires previous knowledge of the available data repositories. Thus, the iTwins Repository API provides a way to discover which data repositories contain data for your iTwin.

Additionally, there are many external data repositories used for digital twins. Use the repository endpoints in the iTwins API to associate these external repositories to your digital twin.

Client Packages

Open source Typescript client packages are available for the iTwins API:


What is the difference between the Projects API and the iTwins API?

Historically, Bentley has built cloud software with a heavy focus on the engineering project lifecycle. The Projects API focuses on managing the iTwin Platform project. As iTwin Platform grew, we realized not all digital twins are projects, and thus the iTwins API was created to support digital twins for all engineering disciplines and phases. Fundamentally, the iTwins API is a generalized version of the Projects API, supporting many of the same functions, but not specific to just projects.

What about my existing projects? Will I need to recreate them as iTwins?

Your Projects are available in the iTwins API as iTwins with class Endeavor and subClass Project. Your Project's id is the same as your iTwin's id, thus you can transition your software to use the iTwins API, and your existing projects will exist as iTwins. Therefore, you do not need to recreate them as iTwins. Furthermore, projects created via the Project API will always be available via the iTwins API (as iTwins with class Endeavor and subClass Project), and likewise iTwins with class Endeavor and subClass Project will be available via the Projects API.

What if I have some software using the Projects API and some using the iTwins API?

That is perfectly fine. You can migrate your software piece-by-piece to the iTwins API. It does not need to be an all-or-none effort. An iTwin with class Endeavor and subClass Project is available in both the iTwins API and the Projects API, using the same id, thus as you transition your software over to the iTwins API, the projects created via the Projects API will work in the iTwins API. With that being said, keep in mind if you create iTwins with a class/subClass different than Endeavor/Project, they will not be available in the Projects API (they aren't projects).