Cintoo User API

openapi: 3.2.0
info:
  version: 2.0.0
  title: Cintoo Open User API
  description: 'Cintoo Open API 1.x documentation: https://aec.cintoo.com/api


    BETA: API v2 endpoints tagged "BETA" are available in beta-version, meaning that changes may be done later on.'
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: API Support
    email: support@cintoo.com
  x-logo:
    url: ./assets/logo_api.svg
    altText: Cintoo API
servers:
- url: https://aec.cintoo.com
security:
- oauth2: []
tags:
- name: User
paths:
  /api/2/accounts/{accountRef}/users/bulk-invite:
    post:
      summary: Invite users
      operationId: inviteUsers
      description: 'BETAInvite users to an account


        This endpoint is *idempotent* which means it applies the state requested by the caller.

        It can be used to invite users to an account with a set of accountRole

        or it can be used to grant new accountRoles to existing users.


        Users that are new to the Cintoo cloud platform are expected to receive an invitation email where they will be able to define a password.


        Requires the caller:

        * to have permission `account:administrators:write` to invite users as administrators

        * to have permission `account:project-managers:write` to invite users as project managers

        * to have permission `account:project-listers:write` to invite users as project listers

        * to have permission `workzone:members:write` to invite users without specific account role


        If any of the roles is invalid or if some roles are not allowed for the caller, then the whole request returns an error,

        no invitation are sent and no change is applied.'
      tags:
      - User
      parameters:
      - $ref: '#/components/parameters/accountRef'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                - email
                properties:
                  email:
                    type: string
                  roles:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccountRoles'
                    uniqueItems: true
      responses:
        '201':
          description: User(s) have been successfully invited with requested AccountRoles
        4XX:
          $ref: '#/components/responses/UnexpectedError'
      x-codeSamples:
      - lang: cURL
        source: "export TOKEN=...\nexport ACCOUNTUUID=...\n\ncurl --request POST --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/users/bulk-invite\" \\\n  --header \"Authorization: Bearer $TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '[\n    { \"email\":\"admin@example.com\", \"roles\": [\"administrator\"] },\n    { \"email\":\"manager@example.com\", \"roles\": [\"administrator\", \"projectManager\"] },\n    { \"email\":\"joe@example.com\" }\n  ]'\n"
      - lang: Python
        source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\ntoken = \"...\"\n\nresponse = requests.post(\n  \"https://%s/api/2/accounts/%s/users/bulk-invite\"\n    % (host, accountUUID),\n  headers = { \"Authorization\": \"Bearer %s\" % token },\n  json = [\n    { \"email\":\"admin@example.com\", \"roles\": [\"administrator\"] },\n    { \"email\":\"manager@example.com\", \"roles\": [\"administrator\", \"projectManager\"] },\n    { \"email\":\"joe@example.com\" }\n  ]\n)\nprint(response.status_code)\nprint(response.json())\n"
      - lang: TypeScript
        source: "\nconst host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/users/bulk-invite`;\nconst res = await fetch(url, {\n  method: \"POST\",\n  headers: {\n    \"Authorization\": `Bearer ${token}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify(\n    [\n        { \"email\":\"admin@example.com\", \"roles\": [\"administrator\"] },\n        { \"email\":\"manager@example.com\", \"roles\": [\"administrator\", \"projectManager\"] },\n        { \"email\":\"joe@example.com\" }\n      ]\n  ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n"
  /api/2/accounts/{accountRef}/users:
    get:
      summary: List users
      operationId: getUsers
      description: 'BETAList available users into this account.

        Data is anonymized for not confirmed users.


        Requires the caller to have one of following permissions:

        * `account:users:read`

        * `workzone:members:write` on any work zone inside the account'
      tags:
      - User
      parameters:
      - name: accountRef
        required: true
        $ref: '#/components/parameters/accountRef'
      responses:
        '200':
          description: List and content of the Users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        4XX:
          $ref: '#/components/responses/UnexpectedError'
      x-codeSamples:
      - lang: cURL
        source: "export TOKEN=...\nexport ACCOUNTUUID=...\n\ncurl --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/users\" \\\n  --header \"Authorization: Bearer $TOKEN\"\n"
      - lang: Python
        source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\ntoken = \"...\"\n\nresponse = requests.get(\n  \"https://%s/api/2/accounts/%s/users\"\n    % (host, accountUUID),\n  headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\nprint(response.json())\n"
      - lang: TypeScript
        source: "\nconst host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/users`;\nconst res = await fetch(url, {\n  headers: {\n    \"Authorization\": `Bearer ${token}`,\n  },\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n"
  /api/2/accounts/{accountRef}/users/{userRef}:
    get:
      summary: Get user details
      operationId: getUser
      description: 'BETADetails about a given user into this account.

        Data is anonymized in case the user is not confirmed.


        Requires the caller to have one of following:

        * `account:users:read`

        * `workzone:members:write` on any work zone inside the account'
      tags:
      - User
      parameters:
      - name: accountRef
        required: true
        $ref: '#/components/parameters/accountRef'
      - name: userRef
        required: true
        $ref: '#/components/parameters/userRef'
      responses:
        '200':
          description: Details about the user into this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        4XX:
          $ref: '#/components/responses/UnexpectedError'
      x-codeSamples:
      - lang: cURL
        source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport USERREF=...\n\ncurl --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/users/$USERREF\" \\\n  --header \"Authorization: Bearer $TOKEN\"\n"
      - lang: Python
        source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nuserRef = \"...\"\ntoken = \"...\"\n\nresponse = requests.get(\n  \"https://%s/api/2/accounts/%s/users/%s\"\n    % (host, accountUUID, userRef),\n  headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\nprint(response.json())\n"
      - lang: TypeScript
        source: "\nconst host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst userRef = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/users/${userRef}`;\nconst res = await fetch(url, {\n  headers: {\n    \"Authorization\": `Bearer ${token}`,\n  },\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n"
components:
  parameters:
    accountRef:
      name: accountRef
      in: path
      required: true
      description: The Id or Urn of the account
      schema:
        oneOf:
        - $ref: '#/components/schemas/AccountUrn'
        - $ref: '#/components/schemas/AccountId'
    userRef:
      name: userRef
      in: path
      required: true
      description: The Id or Urn of the user
      schema:
        $ref: '#/components/schemas/UserRef'
  schemas:
    UserRef:
      oneOf:
      - $ref: '#/components/schemas/UserUrn'
      - $ref: '#/components/schemas/UserId'
    AccountRoles:
      type: string
      enum:
      - administrator
      - projectLister
      - projectManager
    User:
      type: object
      required:
      - id
      - type
      - api1Id
      - firstName
      - email
      x-tags:
      - User
      properties:
        id:
          readOnly: true
          $ref: '#/components/schemas/UserUrn'
        type:
          type: string
          enum:
          - user
        api1Id:
          $ref: '#/components/schemas/UserOldId'
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe
        email:
          type: string
          format: email
        company:
          type: string
          example: Cintoo
        title:
          type: string
          example: Account Manager
        avatar:
          type: string
          format: uri
        accountRoles:
          type: array
          description: "Account-level roles assigned to this user. Visibility depends on caller's permissions:\n\nVisibility rules:\n- Field is omitted if caller has none of the role read permissions\n- Field is included with filtered roles based on caller's permissions:\n  - `account:administrators:read`: can see administrator role\n  - `account:project-managers:read`: can see projectManager role\n  - `account:project-listers:read`: can see projectLister role\n\nExamples:\n- Account Owner/Admin (has all three read permissions): sees all roles (administrator, projectManager, projectLister)\n- Project Manager (has only project-managers:read): sees only projectManager role\n- Normal user (has no read permissions): field is omitted entirely\n\nNote: The accountOwner role is never exposed in this field.\n"
          items:
            $ref: '#/components/schemas/AccountRoles'
          example:
          - administrator
          - projectManager
    UserOldId:
      type: string
      pattern: ^[-_0-9a-zA-Z]+$
      description: Base64url encoding of "user-{id}"
    Error:
      type: object
      required:
      - status
      - title
      properties:
        status:
          type: integer
          format: int32
        title:
          type: string
        detail:
          type: string
          description: human readable description of the error in english
        errorCode:
          type: string
          description: detailed code describing error, can be used to map to a localized message
        errorValues:
          type: object
          description: values implied in the error, typically an input parameter, can be used to include in a localized message
    AccountUrn:
      type: string
      description: '"urn:cintoo:account:" followed by an UUIDv4

        '
    UserId:
      allOf:
      - $ref: '#/components/schemas/Uuid'
      example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368
    UserUrn:
      type: string
      description: '"urn:cintoo:user:" followed by an UUIDv4

        '
    Uuid:
      type: string
      description: UUIDv4
      format: uuid
      example: 156fff1a-0ef7-4335-891a-627928a19e29
    AccountId:
      allOf:
      - $ref: '#/components/schemas/Uuid'
      example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368
  responses:
    UnexpectedError:
      description: unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            '400':
              value:
                status: 400
                title: Bad Request
            '401':
              value:
                status: 401
                title: Unauthorized
            '403':
              value:
                status: 403
                title: Forbidden
            '404':
              value:
                status: 404
                title: Not Found
            '405':
              value:
                status: 405
                title: Method Not Allowed
            '406':
              value:
                status: 406
                title: Not Acceptable
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://aec.cintoo.com/oauth/authorize
          tokenUrl: https://aec.cintoo.com/oauth/token
          scopes: {}
          refreshUrl: https://aec.cintoo.com/oauth/token
x-tagGroups:
- name: General
  tags:
  - errors_list
  - internal_information
  - token_management
  - Permissions
  - Authentication
- name: Resources
  tags:
  - Resources
- name: Tenant
  tags:
  - Tenant
- name: Account
  tags:
  - Account
  - Subscription
  - Role
  - User
  - Group
  - Trusted Device
- name: Subscription
  tags:
  - Usage Report
- name: Project
  tags:
  - Project
  - Members
  - Workzone
- name: Project Data
  tags:
  - File
  - Annotation
  - Saved View
  - Share Link
  - Crop
  - Measurement
  - Tag List
  - Tag
- name: Jobs
  tags:
  - Progress Monitoring
  - Import Model
  - Export Scene
  - Segmentation
  - Video360
  - Import IDD
- name: Integrations
  tags:
  - Integrations
  - Konekt
  - Autodesk
  - Procore
- name: Tutorials
  tags:
  - tuto_upload_file
  - understand_tag_data