Cintoo Open API (2.0.0)

The Cintoo API specification document you are viewing is compliant with the Open API Specification 3.0.3 and can be exported to a json format that can be used by the API tool of your liking.

It also means the generated json will contain all the details present in this documentation about the

• JSON Objects schema being returned
• The status codes
• The authentication
• The verbs/paths/resources

• The API is resource oriented
• The encoding is done in utf-8
• Do not hesitate to click on the Download button to get the openapi.json file generated and import in your favorite API client
• Any Cintoo valid user can use the API

With Cintoo Cloud API comes a Sandbox, which means a testing environment. This Sandbox is a separate tenant from the Cintoo Cloud platform that you are already familiar with.

The Sandbox is at your disposal so that you can test and use the API with no consequence on your production data (no unfortunate deletion by mistake for example).

Sandbox restrictions

• Scan capacity of 20 scans per user.
• Company SSO (if any) is not applicable since the Sandbox uses a different account.
• Please contact support@cintoo.com to get the invitation link to the Sandbox account.
• You can use the same email but you will be asked to set a new password by clicking on the invitation link.
• Please note that this is an experimental platform, so we reserve the right to refresh/delete the data (unlike the production platform).
• There is no limit in time for using the Sandbox.
• The BIM & CAD Module (BCM) is activated in this Sandbox, so feel free to use your BIM or CAD model in this testing environment.

Registering to the Sandbox / Cintoo Cloud API

Please contact our Support Team support@cintoo.com to be invited to the Sandbox and get all the documentation for Cintoo Cloud API.

The Cintoo API relies on JWT Tokens for authenticating users with the standard combination Access Token+ Refresh Token.

Note that the first acquisition of the token pair requires a manual step (see below) for security reasons, then it can be fully automated.

Access Tokens and Refresh Tokens

There are 2 kind of tokens:

• Access token:
  • is short lived (3h)
  • is used to authenticate each query
  • is personal and should not be shared, except for service users (see Token management recipes at the end of the documentation)
  • is a JWT and is stateless, ie. there is NO limit of Access Token being valid for a given user simultaneously, and can be used in parallel.
  • example of API call to list accounts: curl -H Authorization="Bearer $access_token" https://aec.cintoo.com/api/accounts

Note: Calling the API with an already-used/expired token results in a response with status code 401

• Refresh token:
  • is long lived (months)
  • is used once to obtain a new Access Token + Refresh Token pair.
  • cannot be used to make API calls.
  • is personal and should not be shared, except for service users (see Token management recipes at the end of the documentation)
  • there IS a limit of 10 Refresh Token being valid for a given user simultaneously
  • is stateful and CANNOT be used in parallel, as it is consumed when used
  • example of refresh token call to get a new pair of "Access Token" and "Refresh Token": curl -X POST https://aec.cintoo.com/oauth/token -d "grant_type=refresh_token&refresh_token=$refresh_token"

Note: Calling the API with an already-used/expired token results in a response with status code 401

The token flow

The Cintoo API follows the OAuth 2.0 Authorization Grant Type flow, and supports the PKCE extension which is recommended to provide better security (source: https://oauth.net/2/grant-types/authorization-code/)

Concretely, users are supposed to acquire the token once with a manual step (they have to click on approve), to get a first pair of tokens.

Once this is done, they can script the refresh with a simple curl command.

Note: a refresh token is valid for 21 days. It can be used only once. The refreshing mechanism can be done an unlimited number of times

Generating Tokens

• You are just starting with the Cintoo API and want to test it manually -> look that "Generating the JWT Bearer Token with the cintoo-login.exe"
• You are already familiar with oauth mechanisms/tools -> look at "Using tools/3rd party to manage Tokens from Cintoo Oauth Service"

Generating the Access Token & Refresh Token pair with the cintoo-login.exe

To generate an Access Token with OAuth please use the following nice CLI tool cintoo-login.exe and double click on it.

cintoo-login.exe --url https://aec.cintoo.com/

Opening OAuth page in browser.
To receive your JWT token:
        * Ensure you are logged-in
        * Click on the 'Allow' button
INFO: You have 30s to complete these actions

Which opens this page

Hint: if you wait more than 30s you will have to run the command again Hint: you can change the timeout duration to another value with --timeout 60

Once you click on Allow the page should lead you to:

AND (most importantly) the token appears magically in your cmd output

Hint: Copy paste the Bearer xxxxx to avoid errors

Opening OAuth page in browser.
To receive your JWT token:
        * Ensure you are logged-in
        * Click on the 'Allow' button
INFO: You have 30s to complete these actions
Here is your token: to use it put in the Authorization header (copy paste below):
{"Authorization": "Bearer <access_token>"}
Its validity is of 3h
A new token can be-regenerated simply thanks to this refresh_token: <refresh_token>
Validating token
Success: API Token was successfully validated

Refreshing tokens ie. Generating programmatically a new Access Token + Refresh Token pair

While the Refresh Token is valid (within 21 days), you can consume it to get a new Access-Token + Refresh-Token pair.

Note: consuming the Refresh Token can be done before the expiration of the Access Token Note: consuming the Refresh Token does NOT invalidate other Access Token as they are short lived

Using shell (Linux, OSX)

refresh_token="<Your refresh token>"
curl -X POST https://aec.cintoo.com/oauth/token -d "grant_type=refresh_token&refresh_token=$refresh_token"

Which returns the following

{
    "access_token": "{access_token}",
    "refresh_token": "{refresh_token}",
    "token_type": "Bearer",
    "expires_in": 10800,
    "user_id": "{user_id}"
}

Using powershell (Windows)

$refresh_token = "<Your refresh token>"
$params = @{
    Uri         = 'https://aec.cintoo.com/oauth/token'
    Method      = 'POST'
    Body        = @{
        grant_type     = 'refresh_token'
        refresh_token  = $refresh_token
    }
    ContentType = 'application/x-www-form-urlencoded'
}
Invoke-RestMethod @params

Which returns the following

access_token  : {access_token}
refresh_token : {refresh_token}
token_type    : Bearer
expires_in    : 10800
user_id       : {user_id}

Using tools/3rd party to manage Tokens from Cintoo Oauth Service

The Cintoo API follows the oauth protocol Authorization Code Grant to generate the access-tokens and refresh-tokens.

As such, it is possible to use 3rd party libraries and tools that implement the Oauth2 Authorization Code protocol to manage the tokens (and perform automatic refresh).

The important fields are the following and they match those defined by the authorization code request, authorization code request with PKCE and refreshing access tokens :

The flow in detail for acquiring the first Token pair

This section is here in case you want to build an oauth client for acquiring the first Token pair without the help of the cintoo-login or without 3rd party software.

The term "Client" is going to be described as the originator of the oauth token request.

• Client calls the Cintoo oauth/authorize endpoint from the browser with the following query parameters:

  • the redirect_uri (callback-url) it wants Cintoo to send the authorization code to
  • the state uses a random code made of [a-z0-9]+ with a "correct length". More information about the state-parameters
  • (optional) code_challenge a random code that has been hashed using the SHA256 algorithm. More info on PKCE.

    code_verifier = high-entropy cryptographic random STRING using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" from Section 2.3 of [RFC3986], with a minimum length of 43 characters and a maximum length of 128 characters.

  • (optional but mandatory if code_challenge is set) code_challenge_method : "SHA256"

• Cintoo API returns an html element with an approve button to be clicked by the user that started the action (the same shown in the previous chapter)

• Once the approve button is pressed there is a Form Post URL redirect that will target the redirect_uri provided by the Client with the query parameters : code and state (+ code_challenge and code_challenge_method if specified before)

• The Client should check that the state sent and received are the same to avoid CSRF attacks.

• If they are the same, the Client can then send a POST query to the oauth/token endpoint with the following payload that contains the code it received on the previous steps.

  {
      "code": "{code}",
      "grant_type": "authorization_code",
      "authorization_code": "{redirect_uri}"
  }
  

  or with PKCE

  {
      "code": "{code}",
      "grant_type": "authorization_code",
      "authorization_code": "{redirect_uri}",
      "code_verifier": "{code_verifier}"
  }
  

• Finally the Cintoo API answers the oauth/token with a json object that contains the access_token and refresh_token pair:

  {
      "access_token": "{access_token}",
      "refresh_token": "{refresh_token}",
      "token_type": "Bearer",
      "expires_in": 10800,
      "user_id": "{user_id}"
  }
  

Below you will find an example on how to use the token to do a query.

A good endpoint to start with is the isLogged resource which simply returns 200 and {"success": true} if the token was recognized by the Cintoo API.

We highly recommend that you try it, then start changing the resource type (like accounts for instance) to get used to the API.

Query example for Windows

with cUrl

export HOST=aec.cintoo.com
export TOKEN=...

curl --url "https://{host}/api/2/accounts" --header "Authorization: Bearer $TOKEN"

with Python

import requests

host = "{host}"
token = "..."

response = requests.get(
  "https://%s/api/2/accounts" % host,
  headers = { "Authorization": "Bearer %s" % token}
)
print(response.status_code)
print(response.json())

with Powershell

Copy the code below and try it in your Powershell terminal.

Hint: copy paste this while replacing the xxxxxxx with your token, and call as many Invoke-RestMethod as you want. Note: the token is surrounded by "

$token = "xxxxxxxxxxxxxxxxxx"
$headers = @{
    Authorization="Bearer $token"
    Content='application/json'
}
Invoke-RestMethod -Headers $headers -Method Get -Uri "https://aec.cintoo.com/api/isLogged"

The powershell command line should return this

success
-------
   True

URNs are standard Uniform Resource Names.

Our NID is of course "cintoo", so they look like: urn:cintoo:{object type}:{object id}.

All the endpoints that return an object or a list of objects include a field giving the URN of the object, that you can in turn use to reference this object whenever you need to mention it.

Throughout the API, most endpoints need you to give references to existing objects, like accounts, projects, roles, etc. For example, getting the details of an account will look like:

GET /api/2/accounts/{accountRef}

A reference can be any unambiguous identifier for the object. It typically is either:

• the raw uuid or numerical id, depending on the type of the object:
  • c41aec8b-3b85-4bdd-81e5-c2cfdb8980e8
  • 5
• a URN (Uniform Resource Name), looking like: urn:cintoo:<object type>:<raw uuid or id>. For example:
  • urn:cintoo:account:c41aec8b-3b85-4bdd-81e5-c2cfdb8980e8
  • urn:cintoo:user:5

The URN is the most durable option and should be preferred, each object returned by the API has an urn field holding it, whereas at some point the raw id/uuid objects fields will be deprecated or removed from the objects content.

If your client needs to store identifiers for objects, you should choose the URN,

To keep some level of upward compatibility with the first version of the API, for numerical ids we still support older forms, although they are considered deprecated and using them is discouraged:

• the typed identifier like user-5
• a Base64 url-safe encoded string of the typed identifier: dXNlci01Cg

To communicate errors, the Cintoo API

• fills the HTTP status code defined by the standard: HTTP response status codes

It is consensus in the industry that the status code is the source of truth on whether an API call was successful or not, the body is merely a BONUS.

Error-body returned

We are following this RFC whose content is the following

• The "status" member is a JSON number indicating The HTTP status code ([HTTP], Section 15) generated by the origin server for this occurrence of the problem.

  The "status" member, if present, is only advisory; it conveys the HTTP status code used for the convenience of the consumer. Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly. See Section 5 for further caveats regarding its use.

  Consumers can use the status member to determine what the original status code used by the generator was when it has been changed (e.g., by an intermediary or cache) and when a message's content is persisted without HTTP information. Generic HTTP software will still use the HTTP status code.

• The "title" member is a JSON string containing a short, human-readable summary of the problem type.

  It SHOULD NOT change from occurrence to occurrence of the problem, except for localization (e.g., using proactive content negotiation; see [HTTP], Section 12.1).

  The "title" string is advisory and is included only for users who are unaware of and cannot discover the semantics of the type URI (e.g., during offline log analysis).

• "detail" (string) - The "detail" member is a JSON string containing a human-readable explanation specific to this occurrence of the problem.

  The "detail" string, if present, ought to focus on helping the client correct the problem, rather than giving debugging information.

  Consumers SHOULD NOT parse the "detail" member for information; extensions are more suitable and less error-prone ways to obtain such information.

In addition, 2 extension fields are added:

• errorCode: detailed code describing the error, can be used to map to a localized message
• errorValues: values implied in the error, typically an input parameter, can be used to include in a localized message

The mandatory fields that are always present are : status and title. Others are optional.

Example:

{
    "status": 404,
    "title": "Not Found",
    "detail": "Account 1234 not found",
    "errorCode": "account-not-found",
    "errorValues": {
        "accountId": "1234"
    }
}

So the HTTP response status code is both in the HTTP header, and in the status attribute of the returned JSON object.

For a list of errorCode and errorValues, see the dedicated section Errors List

Each resource needs to have a permission to be accessed. Permissions are represented by three elements:

• domain: the level on which the resource is: tenant, account, project or workzone
• resource: the type of resource, for example users or tags
• right: the right on the resource the permission is giving. Most of the time it will be either read (get/list resource) or write (create, update, delete) but can be another action when finer granularity is needed.

This is represented by a string containing those 3 elements separated by a colon: <domain>:<resource>:<right>. For example account:users:read is the permission to read (view/list) users on the account level.

Here is the list of the currently supported permissions:

• tenant:user-permissions:read
• tenant:user-permissions:write
• account:account:read
• account:account:update-owner
• account:administrators:read
• account:administrators:write
• account:project-listers:read
• account:project-listers:write
• account:project-managers:read
• account:project-managers:write
• account:projects:read (implies project:project:read on all projects of the account)
• account:projects:create
• account:projects:update (implies project:project:update-details on all projects of the account)
• account:projects:delete (implies project:project:delete on all projects of the account)
• account:roles:read
• account:roles:write
• account:subscriptions:read
• account:subscriptions:write
• account:users:read
• account:users:write (implies workzone:members:write on all workzones in the account)
• account:groups:read
• project:project:read
• project:project:delete
• project:project:update-details
• project:project:update-owner
• project:project:update-subscription
• project:annotations:create-integration-link
• workzone:annotations:read
• workzone:annotations:write
• workzone:documents:read
• workzone:documents:write
• workzone:export-jobs-reality-data:write
• workzone:import-jobs-reality-data:write
• workzone:measurements:read
• workzone:measurements:write
• workzone:members:write
• workzone:own-shared-links:read
• workzone:own-shared-links:write
• workzone:reality-data:read
• workzone:reality-data:write
• workzone:savedviews:read
• workzone:savedviews:write
• workzone:tags:read
• workzone:tags:write
• workzone:workzones:read
• workzone:workzones:write
• workzone:progress-monitoring-jobs:read
• workzone:progress-monitoring-jobs:write
• workzone:own-progress-monitoring-jobs:read
• workzone:own-progress-monitoring-jobs:write
• workzone:model-reports:read
• workzone:model-reports:write

Roles

A user is given permissions through roles. There are roles on the different levels detailed below.

Roles at the account level

Roles on an account are currently not modifiable, and are the following:

• Account Member is any user invited to the account
• Account Owner
• Account Administrator
• Project Manager
• Project Lister

An account member has the following permissions:

• account:account:read to view the account
• account:roles:read to view roles on the account
• account:groups:read to view groups on the account

An account owner or account administrator are account members, and have the following additional permissions:

• account:projects:read to list and view all projects on the account
• account:projects:update to update any project on the account
• account:roles:write to create, edit and delete roles on the account
• account:users:read to list users members of the account
• account:users:write to invite or remove users on the account
• account:subscriptions:read to view subscriptions of the account
• account:subscriptions:write to add, update or remove subscriptions on the account
• account:administrators:read to list administrators on the account
• account:administrators:write to invite or remove an administrator
• account:project-managers:read to list project managers on the account
• account:project-managers:write to invite or remove a project manager
• account:project-listers:read to list project listers on the account
• account:project-listers:write to invite or remove a project lister

An account owner has also the permission account:account:update-owner that an account administrator does not have, to set another user as the account owner

A project manager is an account member with the following additional permissions:

• account:projects:read to list and view all projects on the account
• account:projects:create to create new projects
• account:projects:update to update any project
• account:projects:delete to delete any project
• account:roles:write to create, edit and delete roles on the account
• account:users:read to list users of the account
• account:users:write to invite or remove users on the account
• account:subscriptions:read to view subscriptions of the account
• account:project-managers:read to list project managers on the account
• account:project-managers:write to invite or remove a project manager

A project lister is an account member with the following additional permission:

• account:projects:read to list and view all projects of the account

Roles at project and workzone levels

Roles can be created on an account to give permissions on project and workzone levels.

Users and groups are invited to a project with a specific role, thus a user has the role assigned to him, but also the roles of the groups he belongs to. A user's permissions are determined by adding the permissions of all his roles.

Currently the permissions given to a role are restricted to the following:

• project:project:update-details + project:project:delete allows the user to manage the project
• workzone:workzones:read + workzone:workzones:write allows the user to create, modify and delete work zones
• workzone:reality-data:read allows the user to view reality data
• workzone:reality-data:write + workzone:import-jobs-reality-data:write allows the user to import or delete scans
• workzone:export-jobs-reality-data:write allows the user to export and download reality data
• workzone:annotations:read allows the user to view annotations
• workzone:annotations:read + workzone:annotations:write allows the user to create, edit and delete annotations, and assign notes to team members
• workzone:measurements:read + workzone:measurements:write allows the user to add and view 3D measurements
• workzone:own-shared-links:read + workzone:own-shared-links:write allows the user to create, edit and delete shared links
• workzone:documents:read + workzone:documents:write allows the user to upload and download documents
• workzone:tags:read allows the user to view tags
• workzone:tags:write allows the user to import, create, edit and delete tags
• workzone:savedviews:read allows the user to view saved views
• workzone:savedviews:read + workzone:savedviews:write allows the user to create, edit and delete saved views
• workzone:members:write allows the user to add and remove team members
• workzone:progress-monitoring-jobs:read + workzone:progress-monitoring-jobs:write
  • workzone:own-progress-monitoring-jobs:read + workzone:own-progress-monitoring-jobs:write
  • workzone:model-reports:read + workzone:model-reports:write allows the user to create, edit, download and delete progress monitoring reports

Any member of a project also automatically has the following permissions:

• project:project:read on the project
• workzone:workzones:read on the workzone he is member and all its child workzones

A project owner automatically has all permissions on the project and all its workzones.

A member having permission workzone:annotations:write on the root work zone of a project, automatically has permission project:annotations:create-integration-link on the project

What to expect with API 2

• Stage 1: API 2 provides features not covered by API 1.
  Most of features are tagged BETA showing that they will continue to mature
• Stage 2: API 2 BETA tags are removed, and API 2 starts covering API 1 features
• Stage 3: API 2 fully covers API 1 scope
• Stage 4: API 1 will have a end of life support date communicated
• Stage 5: API 1 will be decommissioned

Similarities

• Authentication system is the same. Tokens used on API 1 can be used in API 2.
• Do follow the same kind of path ex: /accounts/{accountRef}/projects/{projectRef}/...

Differences

• Reference system is different: API 2 handles new Reference types (URNs), classic references (UUID) and "legacy references" coming from API 1.
  API 1 supports UUID and "legacy references" only.
• Error messages in API 2 follow the RFC 9457 (Problem Details for HTTP APIs).
  In short {"code": ..., "message": ...} becomes {"status": ..., "title": ...}.
• All resources returned by API 2 have multiple ref types (always an URN + UUID or INT)
• POST and PUT endpoints do return full objets (normally available with a GET)
• Objects returned from API 1 and API 2 differ

Endpoints only in API 1

• Report Projects Last Accessed Date
• Report Users Last Activity Date
• Partial Update project : change of subscription only
• List Tag Lists
• Create/Update/Delete a Tag List
• List/Get Group
• List/Get Users

Endpoints only in API 2

• Create a Project
• Update project : any field can be changed (owner, description, subscription,...)
• List Workzones
• Remove user from Project
• Get pre-signed urls for multiple blobs
• Download a blob
• Create/Update/Delete Role
• Get subscription

Endpoints both in API 1 and in API 2

• List Projects
• Get a Project
• List Files
• List/Get Roles
• List subscription