openapi: 3.0.1
info:
  title: 'User Store REST Service: API Specification'
  description: The User Store REST Service is providing REST api endpoints to stored
    user related data.
  version: 1.16.0-CR1
servers:
- description: ''
  url: https://api.uat.btx.fr.banqup.com/userstore
- description: ''
  url: https://api.uat.btx.eu.banqup.com/userstore
tags:
- name: Users
  description: |-
    Users represent people logging, accessing the different spaces.
    The User resource endpoints are used to set and retrieve the personal preferences of a user in the context of specific space.
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Internal Users
  description: This is a set of internal API call only intended to be used by BTX
    Solution Service or Communication Service. They are restricted to ensure that
    retrieval of sensitive user information is done in consistent and secure way.
  x-BTX:
    unDocumented: 'false'
    internal: 'true'
paths:
  /v1/tokens:
    get:
      tags:
      - Users
      summary: Get current user tokens
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Get current user tokens"
      operationId: listCurrentUserTokens
      parameters:
      - name: page
        in: query
        description: Zero-based page index, cannot be negative, default 0
        schema:
          maximum: 10737418
          minimum: 0
          type: integer
          format: int32
          default: 0
        example: 20
      - name: pageSize
        in: query
        description: 'Page size. Minimum 1, maximum: 200, default 20'
        schema:
          maximum: 200
          minimum: 1
          type: integer
          format: int32
          default: 20
        example: 20
      - name: includeTotalElements
        in: query
        description: Return the totalElements number of entries in the response
        schema:
          type: boolean
        example: true
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTokensResponse'
              example:
                tokens:
                - id: 206622c5-6625-418b-8314-0efbea0cf318
                  subject: 71b2f1b5-47ae-4df1-985d-fe8cc7b2f42f
                  fcmToken: d8OywRA9S7A:APA91bHkV1YOa_W1-2Qg4dSkjXJv
                  deviceId: E1z8qjwKoYHnmzH0LMogRA
                  deviceType: PHONE
                  platform: IOS
                  appId: A9x3Kz7LmQp1
                  appVersion: 1.0.1
                  appName: Banqup
                  locale: nl-BE
                  lastActiveAt: 2025-05-06T14:23:45Z
                totalElements: 10
                currentPage: 0
                pageSize: 1
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
  /v1/tokens/{deviceId}/{appId}:
    put:
      tags:
      - Users
      summary: Replace user token for specified device and app
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Replace user token for specified device and app"
      operationId: replaceToken
      parameters:
      - name: deviceId
        in: path
        description: The device identifier
        required: true
        schema:
          type: string
      - name: appId
        in: path
        description: The app identifier
        required: true
        schema:
          type: string
      requestBody:
        description: Token data to replace
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenPutRequest'
            example:
              fcmToken: d8OywRA9S7A:APA91bHkV1YOa_W1-2Qg4dSkjXJv
              deviceType: PHONE
              platform: IOS
              appVersion: 1.0.1
              appName: Banqup
              locale: nl-BE
        required: true
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              example:
                id: 206622c5-6625-418b-8314-0efbea0cf318
                subject: 71b2f1b5-47ae-4df1-985d-fe8cc7b2f42f
                fcmToken: d8OywRA9S7A:APA91bHkV1YOa_W1-2Qg4dSkjXJv
                deviceId: E1z8qjwKoYHnmzH0LMogRA
                deviceType: PHONE
                platform: IOS
                appId: A9x3Kz7LmQp1
                appVersion: 1.0.1
                appName: Banqup
                locale: nl-BE
                lastActiveAt: 2025-05-06T14:23:45Z
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
  /v1/users/me:
    put:
      tags:
      - Users
      summary: Create or update my own user
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Create or update the current user based on the JWT token. If the user
        exists, update user information and set status to ACTIVE. If the user does
        not exist and has a valid email, create the user with ACTIVE status. Application
        tokens (without email) cannot create users."
      operationId: createOrUpdateMe
      responses:
        '200':
          description: User created or updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResult'
              example:
                firstName: John
                lastName: Doe
                email: john.doe@example.com
                subject: 0a351c75-42f1-4721-a4ea-f3f992a4150d
                status: ACTIVE
        '400':
          description: Bad Request - Application token cannot create user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
  /v1/preferences/entities/{entityId}:
    get:
      tags:
      - Users
      summary: Get user's entities preferences
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Get user's entity-specific preferences"
      operationId: getEntityPreferences
      parameters:
      - name: entityId
        in: path
        description: The entity's unique identifier
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
              example:
                locale: de
                timezone: cet
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
    put:
      tags:
      - Users
      summary: Update user's entities preferences
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Update user's entity-specific preferences"
      operationId: updateEntityPreferences
      parameters:
      - name: entityId
        in: path
        description: The entity's unique identifier
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: User's entity-related preferences to update
        content:
          application/json:
            schema:
              type: object
            example:
              settings:
                locale: de
                timezone: cet
        required: true
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
              example:
                locale: de
                timezone: cet
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
    delete:
      tags:
      - Users
      summary: Delete entity's preferences
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Delete the preferences of a user's entity"
      operationId: deleteEntityPreferences
      parameters:
      - name: entityId
        in: path
        description: The entity's unique identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: keys
        in: query
        description: Keys that represent settings properties to be deleted
        schema:
          type: string
      responses:
        '204':
          description: No Content
          content:
            application/json: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
  /v1/preferences/entities/{entityId}/spaces/{spaceId}:
    get:
      tags:
      - Users
      summary: Get user's spaces preferences
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Get user's space-specific preferences"
      operationId: getSpacePreferences
      parameters:
      - name: entityId
        in: path
        description: The entity's unique identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: spaceId
        in: path
        description: The space's unique identifier
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
              example:
                locale: de
                timezone: cet
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
    put:
      tags:
      - Users
      summary: Update user's spaces preferences
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Update user's space-specific preferences"
      operationId: updateSpacePreferences
      parameters:
      - name: entityId
        in: path
        description: The entity's unique identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: spaceId
        in: path
        description: The space's unique identifier
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: User's space-related preferences to update
        content:
          application/json:
            schema:
              type: object
            example:
              settings:
                locale: de
                timezone: cet
        required: true
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
              example:
                locale: de
                timezone: cet
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
    delete:
      tags:
      - Users
      summary: Delete user's space preferences
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Delete the preferences of a specific user's space"
      operationId: deleteSpacePreferences
      parameters:
      - name: entityId
        in: path
        description: The entity's unique identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: spaceId
        in: path
        description: The space's unique identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: keys
        in: query
        description: Keys that represent settings properties to be deleted
        schema:
          type: string
      responses:
        '204':
          description: No Content
          content:
            application/json: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
  /v1/preferences:
    get:
      tags:
      - Users
      summary: Get current user preferences
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Get current user preferences, if not found, create a new user based
        on the access token."
      operationId: getUserPreferences
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
              example:
                locale: de
                timezone: cet
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
    put:
      tags:
      - Users
      summary: Update user global preferences
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Update user's global preferences"
      operationId: updateGlobalPreferences
      requestBody:
        description: User global preferences to update
        content:
          application/json:
            schema:
              type: object
            example:
              settings:
                locale: de
                timezone: cet
        required: true
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
              example:
                locale: de
                timezone: cet
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
    delete:
      tags:
      - Users
      summary: Delete current user preferences
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Delete current user preferences based on the access token."
      operationId: deleteUserPreferences
      parameters:
      - name: keys
        in: query
        description: Keys that represent settings properties to be deleted
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
components:
  schemas:
    DeviceType:
      type: string
      description: Device type
      example: PHONE
      enum:
      - PHONE
      - TABLET
      - WEB
    ListTokensResponse:
      type: object
      properties:
        tokens:
          type: array
          description: List of user tokens
          items:
            $ref: '#/components/schemas/TokenResponse'
        totalElements:
          type: integer
          description: Total number of items in the database that correspond to this
            search criteria
          format: int64
        currentPage:
          type: integer
          description: Current page
          format: int32
        pageSize:
          type: integer
          description: Response page size
          format: int32
    PlatformType:
      type: string
      description: Platform type
      example: IOS
      enum:
      - ANDROID
      - IOS
      - WEB
    TokenResponse:
      type: object
      properties:
        id:
          type: string
          description: Token identifier
          format: uuid
        subject:
          type: string
          description: User subject
        fcmToken:
          type: string
          description: FCM Token
        deviceId:
          type: string
          description: Device id
        deviceType:
          $ref: '#/components/schemas/DeviceType'
        platform:
          $ref: '#/components/schemas/PlatformType'
        appId:
          type: string
          description: App id
        appVersion:
          type: string
          description: App version
        appName:
          type: string
          description: App name
        locale:
          type: string
          description: Locale
        lastActiveAt:
          type: string
          description: Last active
          format: date-time
    ApiErrorProblemDetail:
      required:
      - error
      - requestId
      - timestamp
      type: object
      properties:
        status:
          type: integer
          format: int32
        error:
          type: string
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        type:
          type: string
          format: uri
        title:
          type: string
        detail:
          type: string
        instance:
          type: string
          format: uri
        problems:
          type: array
          items:
            $ref: '#/components/schemas/NestedProblem'
        properties:
          type: object
          additionalProperties:
            type: object
    NestedProblem:
      required:
      - detail
      - error
      - title
      type: object
      properties:
        error:
          type: string
        title:
          type: string
        detail:
          type: string
        type:
          type: string
          format: uri
    TokenPutRequest:
      type: object
      properties:
        fcmToken:
          type: string
          description: FCM Token
        deviceType:
          $ref: '#/components/schemas/DeviceType'
        platform:
          $ref: '#/components/schemas/PlatformType'
        appVersion:
          type: string
          description: App version
          example: 1.0.1
        appName:
          type: string
          description: App name
        locale:
          type: string
          description: Locale
    UserResult:
      type: object
      properties:
        firstName:
          type: string
          description: First name of user
        lastName:
          type: string
          description: Last name of user
        email:
          type: string
          description: Email address of user
        phone:
          type: string
          description: Phone number of user
        subject:
          type: string
          description: Subject id of user
        status:
          type: string
          description: Status of user
    UserRequest:
      type: object
      properties:
        firstName:
          type: string
          description: First name of user
        lastName:
          type: string
          description: Last name of user
        email:
          type: string
          description: Email address of user
        phone:
          type: string
          description: Phone number of user
        subject:
          type: string
          description: Subject of user
    UserCommunicationListResult:
      type: object
      properties:
        users:
          type: array
          description: List of user communication data
          items:
            $ref: '#/components/schemas/UserCommunicationResult'
    UserCommunicationResult:
      type: object
      properties:
        subject:
          type: string
          description: Subject id of user
          example: 4e9f1209-c822-4953-b1cc-b5c71e9f5977
        email:
          type: string
          description: Email address of user
          example: bob@example.com
        firstName:
          type: string
          description: User's first name
          example: Bob
        lastName:
          type: string
          description: User's last name
          example: Barker
        phone:
          type: string
          description: Phone number of user
          example: '+32472123456'
        tokens:
          type: array
          description: User tokens
          items:
            $ref: '#/components/schemas/TokenResponse'
        preferences:
          type: object
          additionalProperties:
            type: object
            description: User's space-specific communication preferences (contents
              of communicationData from space-level settings). Only present when ?include=preferences
              is passed.
          description: User's space-specific communication preferences (contents of
            communicationData from space-level settings). Only present when ?include=preferences
            is passed.
    UsersCommunicationRequest:
      required:
      - entityId
      - spaceId
      type: object
      properties:
        entityId:
          type: string
          description: Entity id
          format: uuid
          example: 828b4676-5db5-4169-9518-cabc52cd2873
        spaceId:
          type: string
          description: Space id
          format: uuid
          example: c5f2158c-2188-45f8-a486-e21811306e96
        subjects:
          uniqueItems: true
          type: array
          description: User subjects
          items:
            type: string
            description: User subject
            format: uuid
    AllUserResult:
      type: object
      properties:
        users:
          type: array
          description: List of users' info
          items:
            $ref: '#/components/schemas/UserResult'
    SubjectList:
      type: object
      properties:
        subjects:
          type: array
          description: List of subjects
          items:
            type: string
            description: List of subjects
    UserSettings:
      type: object
      properties:
        empty:
          type: boolean
      additionalProperties:
        type: object
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.uat.btx.fr.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.uat.btx.fr.banqup.com/oauth2/auth
          tokenUrl: https://api.uat.btx.fr.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
