openapi: 3.2.0
info:
  title: Live Objects REST API Guide Users management API
  description: API description for Live Objects service
  contact:
    name: Live Objects Support
    url: https://liveobjects.orange-business.com/#/cms/support
  version: 2026.7.0
servers:
- url: https://liveobjects.orange-business.com
security:
- X-API-KEY: []
  OAuth2.0: []
tags:
- name: Users management
  description: manage users
paths:
  /api/v0/users:
    get:
      tags:
      - Users management
      summary: List all users in a tenant account
      description: 'Restricted to API keys with at least one of the following roles: USER_R.'
      operationId: listUsers
      parameters:
      - name: size
        in: query
        description: the maximum number of items per page (optional, highest value is 1000)
        required: false
        schema:
          type: string
          default: '20'
      - name: page
        in: query
        description: the requested page number (optional)
        required: false
        schema:
          type: string
          default: '0'
      - name: login
        in: query
        description: 'login of tenant account (optional) ex: "login_name" (deprecated, please use /api/v2 endpoints instead)'
        required: false
        schema:
          type: string
      - name: email
        in: query
        description: 'email of tenant account (optional) ex: "myAccount@mail.com"'
        required: false
        schema:
          type: string
      - name: externalProvider
        in: query
        description: 'external (IDP) provider of tenant account (optional) ex: "SIU" (deprecated, please use /api/v2 endpoints instead)'
        required: false
        schema:
          type: string
      - name: externalId
        in: query
        description: 'external (IDP) identifier of tenant account (optional) ex: "57xxxxxxxxxxxxxxxxxxxxxx" (deprecated, please use /api/v2 endpoints instead)'
        required: false
        schema:
          type: string
      - name: externalLogin
        in: query
        description: 'external (IDP) login of tenant account (optional) ex: "login_name" (deprecated, please use /api/v2 endpoints instead)'
        required: false
        schema:
          type: string
      - name: userState
        in: query
        description: 'userState of tenant account (optional) ex: "[enabled]"'
        required: false
        schema:
          type: array
          items:
            type: string
          uniqueItems: true
      responses:
        '200':
          description: The list of the Users of the Tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageableUserForList'
        '400':
          description: An ErrorMessage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
        '403':
          description: Request forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
        '404':
          description: Unknown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
    post:
      tags:
      - Users management
      summary: Create a user
      description: 'Usage of this API will be reported in your access log under ''user'' category.<br/><br/>Restricted to API keys with at least one of the following roles: USER_W.'
      operationId: createUserAccount
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreationCustomerDefinition'
        required: true
      responses:
        '200':
          description: The created User
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: An ErrorMessage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
        '403':
          description: Request forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
        '404':
          description: Unknown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
  /api/v0/users/{userId}:
    get:
      tags:
      - Users management
      summary: Get details of a user in a tenant account
      description: 'Restricted to API keys with at least one of the following roles: USER_R.'
      operationId: getUser
      parameters:
      - name: userId
        in: path
        description: the User Identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The User data are available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: An ErrorMessage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
        '403':
          description: Request forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
        '404':
          description: Unknown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
    post:
      tags:
      - Users management
      summary: Update a user
      description: 'Usage of this API will be reported in your access log under ''user'' category.<br/><br/>Restricted to API keys with at least one of the following roles: USER_W.'
      operationId: updateUser
      parameters:
      - name: userId
        in: path
        description: the User Identifier. Expected identifier (max 24 characters)
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateCustomerDefinition'
        required: true
      responses:
        '200':
          description: The User data are updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: An ErrorMessage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
        '403':
          description: Request forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
        '404':
          description: Unknown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
    delete:
      tags:
      - Users management
      summary: Delete a user in a tenant account
      description: 'Usage of this API will be reported in your access log under ''user'' category.<br/><br/>Restricted to API keys with at least one of the following roles: USER_W.'
      operationId: deleteUser
      parameters:
      - name: userId
        in: path
        description: the User Identifier. Expected identifier (max 24 characters)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deletion of the user is done, nothing in the response
        '400':
          description: An ErrorMessage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
        '403':
          description: Request forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
        '404':
          description: Unknown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebErrorResponse'
components:
  schemas:
    WebErrorResponse:
      type: object
      description: Error response
      properties:
        id:
          type: string
          description: Unique identifier of this error instance
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Short error description
        details:
          type: string
          description: Detailed error description
      required:
      - code
      - id
      - message
    User:
      type: object
      description: body of user data
      properties:
        id:
          type: string
          description: identifier of user
          example: 57FFFFFFFFFFFFFFFFFFFFFF
        login:
          type: string
          description: user login
          example: MyLoginName
        externalIdentity:
          $ref: '#/components/schemas/ExternalIdentity'
        email:
          type: string
          description: user email
          example: me.name@mycompagny.mycom
        tenantId:
          type: string
          description: identifier of tenant account this user will belong to
          example: 51FFFFFFFFFFFFFFFFFFFFFF
        roles:
          type: array
          description: list of user associated roles.
          example:
          - USER_R
          - APIKEY_R
          items:
            type: string
          uniqueItems: true
        state:
          type: string
          description: 'user state : disabled, enabled or suspended'
          example: enabled
        lastAuthentication:
          type: integer
          format: int64
          description: user last authentication timestamp in ms
          example: 1475224200000
        lastResetPassword:
          type: integer
          format: int64
          description: user last password renewal operation timestamp in ms
          example: 1475224200000
        passwordExpiration:
          type: integer
          format: int64
          description: user password expiration timestamp in ms
          example: 1475224200000
        language:
          type: string
          description: the user language, in ISO 639-1 format
          example: en
        portalData:
          description: user portal data
        mainUser:
          type: boolean
          description: user is the tenant's main user
      required:
      - email
      - id
      - login
      - roles
      - state
      - tenantId
    UserCreationCustomerDefinition:
      type: object
      description: body of user creation
      properties:
        login:
          type: string
          description: the user login. If no external identity provider is used, LO identity is used and login must respect the following regular expression <code>[a-zA-Z0-9_-]{3,254}</code> or must be a valid email
          example: MyLoginName
        email:
          type: string
          description: the user email. Expected a valid email (max 254 characters)
          example: me.name@mycompagny.mycom
        roles:
          type: array
          description: list of user associated roles. Basic roles are "USER_R", "USER_W", "API_KEY_R", "API_KEY_W" or any role string supplied at tenant account creation time. Expected array of role names (max all roles, role value max 255 characters). Assigned roles must be included in the roles of the authenticating API key or token.
          example:
          - USER_R
          - APIKEY_R
          items:
            type: string
          uniqueItems: true
        language:
          type: string
          description: 'user language. Expected language ISO 639-1 (example: "en", "fr", "sk", "ro", "es") (case insensitive, max 2 characters)'
      required:
      - email
      - roles
    ExternalIdentity:
      type: object
      description: user's external identity
      properties:
        provider:
          type: string
          description: the external identity provider. Expected string (max 255 characters)
          example: SIU
        id:
          type: string
          description: the external identity identifier. Expected string (max 255 characters)
          example: 44b738a0-b280-11e7-abc4-cec278b6b50a
        login:
          type: string
          description: the external identity login. Expected string (max 255 characters)
          example: bagginsf
      required:
      - provider
    UserForList:
      type: object
      description: body of user data
      properties:
        id:
          type: string
          description: identifier of user
          example: 57FFFFFFFFFFFFFFFFFFFFFF
        login:
          type: string
          description: user login
          example: MyLoginName
        externalIdentity:
          $ref: '#/components/schemas/ExternalIdentity'
        email:
          type: string
          description: user email
          example: me.name@mycompagny.mycom
        tenantId:
          type: string
          description: identifier of tenant account this user will belong to
          example: 51FFFFFFFFFFFFFFFFFFFFFF
        roles:
          type: array
          description: list of user associated roles.
          example:
          - USER_R
          - APIKEY_R
          items:
            type: string
          uniqueItems: true
        state:
          type: string
          description: 'user state : disabled, enabled or suspended'
          example: enabled
        lastAuthentication:
          type: integer
          format: int64
          description: user last authentication timestamp in ms
          example: 1475224200000
        lastResetPassword:
          type: integer
          format: int64
          deprecated: true
          description: user last password renewal operation timestamp in ms. (deprecated, please use unitary get instead)
          example: 1475224200000
        passwordExpiration:
          type: integer
          format: int64
          deprecated: true
          description: user password expiration timestamp in ms. (deprecated, please use unitary get instead)
          example: 1475224200000
        language:
          type: string
          description: the user language, in ISO 639-1 format
          example: en
        portalData:
          description: user portal data
        mainUser:
          type: boolean
          description: user is the tenant's main user
      required:
      - email
      - id
      - login
      - roles
      - state
      - tenantId
    PageableUserForList:
      type: object
      properties:
        page:
          type: integer
          format: int64
          description: 'number of the current page: starts at 0.'
          example: 0
        size:
          type: integer
          format: int64
          description: number of data per page (= maximum number of data in the associated list of data:the last page can have less data)
          example: 1
        totalCount:
          type: integer
          format: int64
          description: total count of data in the complete list.
          example: 1
        data:
          type: array
          description: list of data in this page.
          items:
            $ref: '#/components/schemas/UserForList'
      required:
      - data
      - page
      - size
      - totalCount
    UserUpdateCustomerDefinition:
      type: object
      description: body of user update
      properties:
        login:
          type: string
          description: the user login. If no external identity provider is used, LO identity is used and login must respect the following regular expression <code>[a-zA-Z0-9_-]{3,254}</code> or must be a valid email (deprecated, please use user profiles endpoints instead)
          example: MyLoginName
        email:
          type: string
          description: user email. Expected a valid email (max 254 characters) (deprecated, please use user profiles endpoints instead)
          example: me.name@mycompagny.mycom
        roles:
          type: array
          description: list of user associated roles. Basic roles are "USER_R", "USER_W", "API_KEY_R", "API_KEY_W" or any role string supplied at tenant account creation time. Expected array of role names (max all roles, role value max 255 characters). Assigned roles must be included in the roles of the authenticating API key or token.
          example:
          - USER_R
          - APIKEY_R
          items:
            type: string
          uniqueItems: true
        state:
          type: string
          description: 'user state : disabled, enabled or suspended'
          example: enabled
        language:
          type: string
          description: 'user language. Expected language ISO 639-1 (example: "en", "fr", "sk", "ro", "es") (case insensitive, max 2 characters) (deprecated, please use user profiles endpoints instead)'
          example: EN
        mainUser:
          type: boolean
          description: Set the user as main user. Expected boolean (true/false)
          example: true
  securitySchemes:
    X-API-KEY:
      type: apiKey
      name: X-API-KEY
      in: header
    OAuth2.0:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://liveobjects.orange-business.com/api/v1/oauth2/authorize
          tokenUrl: https://liveobjects.orange-business.com/api/v1/oauth2/token
          refreshUrl: https://liveobjects.orange-business.com/api/v1/oauth2/token
          scopes:
            API_KEY_R: Read parameters and status of an API key.
            API_KEY_W: Create, modify, disable an API key.
            BOOTSTRAP_R: Read parameters and status of the LwM2M Bootstrap configurations and entries.
            BOOTSTRAP_W: Create ans modify LwM2M Bootstrap configurations and entries.
            BUS_CONFIG_R: Read config parameters of a FIFO queue.
            BUS_CONFIG_W: Create, modify a FIFO queue.
            BUS_R: Read data on the Live Objects bus. Minimum permission for the API key of an application collecting data on Live Objects in MQTT(s).
            BUS_W: Publish data on the Live Objects bus.
            CAMPAIGN_R: Read parameters and status of a massive deployment campaign on your Device Fleet.
            CAMPAIGN_W: Create, modify a campaign on your Device Fleet.
            CONNECTOR_ACCESS: Role to set on a external connector API key to allow only MQTT external connector mode
            DATA_PROCESSING_R: Read parameters and status of an event processing rule or a Data decoder.
            DATA_PROCESSING_W: Create, modify, disable an event processing rule or a Data decoder.
            DATA_R: Read the data collected by the Store Service or search into this data using the Search Service.
            DATA_W: Insert a data record to the Store Service. Minimum permission required for the API key of a device pushing data to Live Objects in HTTPS.
            DEVICE_ACCESS: Role to set on a Device API key to allow only MQTT Device mode
            DEVICE_R: Read parameters and status of a Device management.
            DEVICE_W: Create, modify, disable a Device management, send command, modify config, update resource of a Device.
            LOGS_R: Read the logs collected by the Audit Log service. This right allows users to use the Audit Log service as debugging tool.
            SETTINGS_R: Read the tenant account custom settings.
            SETTINGS_W: Create, modify tenant account custom settings.
            USER_R: Read parameters and status of a user.
            USER_W: Create, modify, disable a user.
externalDocs:
  description: Live Objects Developer Guide
  url: https://liveobjects.orange-business.com/doc/html/lo_manual_v2.html
x-examples: ''