openapi: 3.0.3 info: version: 2.0.0 title: Cintoo Open Account Konekt API description: "Cintoo Open API 1.x documentation: https://aec.cintoo.com/api\n\nBETA: API v2 endpoints tagged \"BETA\" are available in beta-version, meaning that changes may be done later on.\n\n# API Specification\n\nThe Cintoo API specification document you are viewing is compliant with the Open API Specification 3.0.3 and can be\nexported to json or yaml format that can be used by the API tool of your liking.\n\nIt also means the generated json/yaml will contain all the details present in this documentation about the\n\n* JSON Objects schema being returned\n* The status codes\n* The authentication\n* The verbs/paths/resources\n\n## Technical details\n\n* The API is **resource oriented**\n* The encoding is done in **utf-8**\n* Do not hesitate to click on the Download button on the top of this page to get the `openapi.json` or `openapi.yaml`\n file generated and import in your favorite API client\n* Any Cintoo valid user can use the API\n\n- - -\n\n## Sandbox\n\nWith Cintoo Cloud API comes a Sandbox, which means a testing environment. This Sandbox is a separate tenant from the\nCintoo Cloud platform that you are already familiar with.\n\nThe Sandbox is at your disposal so that you can test and use the API with no consequence on your production data (no\nunfortunate deletion by mistake for example).\n\n### Sandbox restrictions\n\n* Scan capacity of 20 scans per user.\n* Company SSO (if any) is not applicable since the Sandbox uses a different account.\n* Please contact to get the invitation link to the Sandbox account.\n* You can use the same email but you will be asked to set a new password by clicking on the invitation link.\n* Please note that this is an experimental platform, so we reserve the right to refresh/delete the data (unlike the\n production platform).\n* There is no limit in time for using the Sandbox.\n* The BIM & CAD Module (BCM) is activated in this Sandbox, so feel free to use your BIM or CAD model in this testing\n environment.\n\nRegistering to the Sandbox / Cintoo Cloud API\n\nPlease contact our Support Team to be invited to the Sandbox and get all the documentation for\nCintoo Cloud API.\n\n- - -\n\n## Authentication\n\nThe Cintoo API relies on JWT Tokens for authenticating users with the standard combination `Access Token`+\n`Refresh Token`.\n\nNote that the first acquisition of the token pair requires a manual step (see below) for security reasons, then it can\nbe fully automated.\n\n### Access Tokens and Refresh Tokens\n\nThere are 2 kind of tokens:\n\n* Access token:\n * is short lived (3h)\n * is used to authenticate each query\n * is personal and should not be shared, except for service users (see `Token management recipes` at the end of the\n documentation)\n * is a JWT and is stateless, ie. there is *NO* limit of Access Token being valid for a given user simultaneously,\n and ***can*** be used in parallel.\n * example of API call to list `accounts`:\n `curl -H Authorization=\"Bearer $access_token\" https://aec.cintoo.com/api/accounts`\n\n> ***Note***: Calling the API with an already-used/expired token results in a response with status code `401`\n\n* Refresh token:\n * is long lived (months)\n * is used **once** to obtain a new `Access Token` + `Refresh Token` pair.\n * **cannot** be used to make API calls.\n * is personal and should not be shared, except for service users (see `Token management recipes` at the end of the\n documentation)\n * there ***IS*** a limit of 10 Refresh Token being valid for a given user simultaneously\n * is stateful and ***CANNOT*** be used in parallel, as it is consumed when used\n * example of refresh token call to get a new pair of \"Access Token\" and \"Refresh Token\":\n `curl -X POST https://aec.cintoo.com/oauth/token -d \"grant_type=refresh_token&refresh_token=$refresh_token\"`\n\n> ***Note***: Calling the API with an already-used/expired token results in a response with status code `401`\n\n### The token flow\n\nThe Cintoo API follows the OAuth 2.0 Authorization Grant Type flow, and supports the PKCE extension which is recommended\nto provide better security (source: )\n\nConcretely, users are supposed to acquire the token once with a manual step (they have to click on approve), to get a\nfirst pair of tokens.\n\nOnce this is done, they can script the refresh with\na [simple curl command](#refreshing-tokens-ie-generating-programmatically-a-new-access-token--refresh-token-pair).\n\n> ***Note:*** a refresh token is valid for 21 days. It can be used only once. The refreshing mechanism can be done **an\nunlimited number of times**\n\n### Generating Tokens\n\n* You are just starting with the Cintoo API and want to test it manually -> look that \"Generating the JWT Bearer Token\n with the cintoo-login.exe\"\n* You are already familiar with oauth mechanisms/tools -> look at \"Using tools/3rd party to manage Tokens from Cintoo\n Oauth Service\"\n\n### Generating the Access Token & Refresh Token pair with the cintoo-login.exe\n\nTo generate an Access Token with OAuth please use the following nice CLI\ntool [cintoo-login.exe](https://cintooprodstatic.blob.core.windows.net/api/cintoo-login-1.1.0-signed.exe) and double\nclick on it.\n\n**If you are on a dedicated tenant, please add the argument `--url`.**\n\n```powershell\n.\\cintoo-login-1.1.0-signed.exe --url https://aec.cintoo.com\n\nOpening OAuth page in browser.\nTo receive your JWT token:\n * Ensure you are logged-in\n * Click on the 'Allow' button\nINFO: You have 30s to complete these actions\n```\n\nWhich opens this page\n\n> Hint: if you wait more than 30s you will have to run the command again\n> Hint: you can change the timeout duration to another value with `--timeout 60`\n\n![allow-button](./assets/oauth.png#width=500px;height=350px;)\n\nOnce you click on `Allow` the page should lead you to:\n\n![success](./assets/success.png#width=500px;height=350px;)\n\n*AND* (most importantly) the **token** appears magically in your cmd output\n\n> Hint: Copy paste the `Bearer xxxxx` to avoid errors\n\n```powershell\nOpening OAuth page in browser.\nTo receive your JWT token:\n * Ensure you are logged-in\n * Click on the 'Allow' button\nINFO: You have 30s to complete these actions\nHere is your token: to use it put in the Authorization header (copy paste below):\n{\"Authorization\": \"Bearer \"}\nIts validity is of 3h\nA new token can be-regenerated simply thanks to this refresh_token: \nValidating token\nSuccess: API Token was successfully validated\n```\n\n### Refreshing tokens ie. Generating programmatically a new Access Token + Refresh Token pair\n\nWhile the Refresh Token is valid (within 21 days), you can consume it to get a new Access-Token + Refresh-Token pair.\n\n> ***Note:*** consuming the Refresh Token can be done before the expiration of the Access Token\n> ***Note:*** consuming the Refresh Token does **NOT** invalidate other **Access Token** as they are short lived\n\nUsing shell (Linux, OSX)\n\n```shell\nrefresh_token=\"\"\ncurl -X POST https://aec.cintoo.com/oauth/token -d \"grant_type=refresh_token&refresh_token=$refresh_token\"\n```\n\nWhich returns the following\n\n```json\n{\n \"access_token\": \"{access_token}\",\n \"refresh_token\": \"{refresh_token}\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 10800,\n \"user_id\": \"{user_id}\"\n}\n```\n\nUsing powershell (Windows)\n\n```powershell\n$refresh_token = \"\"\n$params = @{\n Uri = 'https://aec.cintoo.com/oauth/token'\n Method = 'POST'\n Body = @{\n grant_type = 'refresh_token'\n refresh_token = $refresh_token\n }\n ContentType = 'application/x-www-form-urlencoded'\n}\nInvoke-RestMethod @params\n```\n\nWhich returns the following\n\n```powershell\naccess_token : {access_token}\nrefresh_token : {refresh_token}\ntoken_type : Bearer\nexpires_in : 10800\nuser_id : {user_id}\n```\n\n### Using tools/3rd party to manage Tokens from Cintoo Oauth Service\n\nThe Cintoo API follows the oauth\nprotocol [Authorization Code Grant](https://oauth.net/2/grant-types/authorization-code/) to generate the `access-tokens`\nand `refresh-tokens`.\n\nAs such, it is possible to use 3rd party libraries and tools that implement the Oauth2 Authorization Code protocol to\nmanage the tokens (and perform automatic refresh).\n\nThe important fields are the following and they match those defined by\nthe [authorization code request](https://www.oauth.com/oauth2-servers/access-tokens/authorization-code-request/), [authorization code request with PKCE](https://www.oauth.com/oauth2-servers/pkce/authorization-request/)\nand [refreshing access tokens](https://www.oauth.com/oauth2-servers/access-tokens/refreshing-access-tokens/) :\n\n| Field | Value |\n|----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Grant Type | `Authorization Code` or `Authorization Code (With PKCE)` |\n| Callback URL | `localhost` or `127.0.0.1` or `/` |\n| Auth URL | `https://aec.cintoo.com/oauth/authorize` |\n| Access Token URL | `https://aec.cintoo.com/oauth/token` |\n| Refresh Token URL | `https://aec.cintoo.com/oauth/token` |\n| State | use a random code made of `[a-z0-9]+` with a \"correct length\". More information about the [state-parameters](https://auth0.com/docs/secure/attack-protection/state-parameters) |\n| Code Challenge Method (only with PKCE) | `SHA-256` more info on [PKCE](https://www.oauth.com/oauth2-servers/pkce/) |\n\n### The flow in detail for acquiring the first Token pair\n\nThis section is here in case you want to **build an oauth client for acquiring the first Token pair without the help of\nthe cintoo-login or without 3rd party software**.\n\nThe term \"Client\" is going to be described as the originator of the oauth token request.\n\n* Client calls the Cintoo `oauth/authorize` endpoint ***from the browser*** with the following query parameters:\n * the `redirect_uri` (callback-url) it wants Cintoo to send the authorization code to\n * the `state` uses a random code made of `[a-z0-9]+` with a \"correct length\". More information about\n the [state-parameters](https://auth0.com/docs/secure/attack-protection/state-parameters)\n * (optional) `code_challenge` a random code that has been hashed using the SHA256 algorithm. More info\n on [PKCE](https://www.oauth.com/oauth2-servers/pkce/).\n > code_verifier = high-entropy cryptographic random STRING using the\n unreserved characters [A-Z] / [a-z] / [0-9] / \"-\" / \".\" / \"_\" / \"~\"\n from Section 2.3 of [RFC3986], with a minimum length of 43 characters\n and a maximum length of 128 characters.\n * (optional but mandatory if `code_challenge` is set) `code_challenge_method` : \"SHA256\"\n* Cintoo API returns an html element with an `approve` button to be clicked by the user that started the action (the\n same shown in the previous chapter)\n* Once the `approve` button is pressed there is a `Form Post URL redirect` that will target the `redirect_uri` provided\n by the Client with the query parameters : `code` and `state` (+ `code_challenge` and `code_challenge_method` if\n specified before)\n* The Client ***should check*** that the `state` sent and received are the same to avoid CSRF attacks.\n* If they are the same, the Client can then send a `POST` query to the `oauth/token` endpoint with the following payload\n that contains the `code` it received on the previous steps.\n\n ```json\n {\n \"code\": \"{code}\",\n \"grant_type\": \"authorization_code\",\n \"authorization_code\": \"{redirect_uri}\"\n }\n ```\n\n or with PKCE\n\n ```json\n {\n \"code\": \"{code}\",\n \"grant_type\": \"authorization_code\",\n \"authorization_code\": \"{redirect_uri}\",\n \"code_verifier\": \"{code_verifier}\"\n }\n ```\n\n* Finally the Cintoo API answers the `oauth/token` with a json object that contains the `access_token` and\n `refresh_token` pair:\n\n ```json\n {\n \"access_token\": \"{access_token}\",\n \"refresh_token\": \"{refresh_token}\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 10800,\n \"user_id\": \"{user_id}\"\n }\n ```\n\n- - -\n\n## Doing queries\n\nBelow you will find an example on how to use the token to do a query.\n\nA good endpoint to start with is the `isLogged` **resource** which simply returns `200` and `{\"success\": true}` if the\ntoken was recognized by the Cintoo API.\n\nWe highly recommend that you try it, then start changing the resource type (like `accounts` for instance) to get used to\nthe API.\n\n### Query example for Windows\n\n#### with cUrl\n\n```sh\nexport HOST=aec.cintoo.com\nexport TOKEN=...\n\ncurl --url \"https://{host}/api/2/accounts\" --header \"Authorization: Bearer $TOKEN\"\n```\n\n#### with Python\n\n```python\nimport requests\n\nhost = \"{host}\"\ntoken = \"...\"\n\nresponse = requests.get(\n \"https://%s/api/2/accounts\" % host,\n headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\nprint(response.json())\n```\n\n#### with Powershell\n\nCopy the code below and try it in your Powershell terminal.\n\n> Hint: copy paste this while replacing the `xxxxxxx` with your token, and call as many `Invoke-RestMethod` as you want.\n> Note: the token is surrounded by `\"`\n\n```powershell\n$token = \"xxxxxxxxxxxxxxxxxx\"\n$headers = @{\n Authorization=\"Bearer $token\"\n Content='application/json'\n}\nInvoke-RestMethod -Headers $headers -Method Get -Uri \"https://aec.cintoo.com/api/isLogged\"\n```\n\nThe powershell command line should return this\n\n```powershell\nsuccess\n-------\n True\n```\n\n## URNs\n\nURNs are standard [Uniform Resource Names](https://fr.wikipedia.org/wiki/Uniform_Resource_Name).\n\nOur NID is of course \"cintoo\", so they look like: ```urn:cintoo:{object type}:{object id}```.\n\nAll the endpoints that return an object or a list of objects include a field giving the URN of the object, that you can\nin turn use to reference this object whenever you need to mention it.\n\n## References\n\nThroughout the API, most endpoints need you to give *references* to existing objects,\nlike accounts, projects, roles, etc. For example, getting the details of an account will look like:\n\n```\nGET /api/2/accounts/{accountRef}\n```\n\nA *reference* can be any unambiguous identifier for the object. It typically is either:\n\n- the raw uuid or numerical id, depending on the type of the object:\n - ```c41aec8b-3b85-4bdd-81e5-c2cfdb8980e8```\n - ```5```\n- a URN (Uniform Resource Name), looking like: ``urn:cintoo: