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.5.0
servers:
- description: ''
  url: https://api.btx.fr.banqup.com/userstore
- description: ''
  url: https://api.btx.eu.banqup.com/userstore
paths:
  /v1/users:
    post:
      tags:
      - Users
      summary: Create user
      description: 'Create a user with an inactive status <br/> Scope: user_write'
      operationId: createUser
      requestBody:
        description: User to be created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'
            example:
              firstName: Mike
              lastName: Malone
              email: mike.malone@yopmail.com
              subject: sub1
        required: true
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResult'
              example:
                firstName: Mike
                lastName: Malone
                email: mike.malone@yopmail.com
                subject: sub1
                status: INACTIVE
        '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-27 12:34:50
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 409
                error: ABORTED
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27 12:34:50
                type: about:blank
                title: Conflict
                detail: Specific detail about what could not be done.
      security:
      - user_store:
        - user_write
  /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-27 12:34:50
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - user_store: []
    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-27 12:34:50
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
      security:
      - user_store: []
    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-27 12:34:50
                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-27 12:34:50
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - user_store: []
  /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-27 12:34:50
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - user_store: []
    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-27 12:34:50
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
      security:
      - user_store: []
    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-27 12:34:50
                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-27 12:34:50
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - user_store: []
  /v1/preferences:
    get:
      tags:
      - Users
      summary: Get current user preferences
      description: 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-27 12:34:50
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
      security:
      - user_store: []
    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-27 12:34:50
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
      security:
      - user_store: []
    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-27 12:34:50
                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-27 12:34:50
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - user_store: []
  /v1/users:communicationData:
    post:
      tags:
      - Users
      summary: Get communication data of users
      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 communication data of users. It will silently ignore subjects that
        are not found. <br/> Scope: notification_service"
      operationId: getUsersCommunicationData
      requestBody:
        description: Communication data to query
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsersCommunicationRequest'
            example:
              entityId: 828b4676-5db5-4169-9518-cabc52cd2873
              spaceId: c5f2158c-2188-45f8-a486-e21811306e96
              subjects:
              - 4e9f1209-c822-4953-b1cc-b5c71e9f5977
              - d054fa9d-9fc1-4ca8-8eb5-7abea24c242d
              - ea1e4232-b75f-45f2-9c88-91609fb30c8b
        required: true
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCommunicationListResult'
              example:
                users:
                - subject: 4e9f1209-c822-4953-b1cc-b5c71e9f5977
                  email: bob@example.com
                - subject: d054fa9d-9fc1-4ca8-8eb5-7abea24c242d
                  email: john@example.com
                - subject: ea1e4232-b75f-45f2-9c88-91609fb30c8b
                  email: marry@example.com
        '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-27 12:34:50
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
      security:
      - user_store:
        - notification_service
  /v1/users:info:
    post:
      tags:
      - Users
      summary: Get user details by subject IDs
      description: 'Get a list of user information based on the provided subject IDs
        <br/> Scope: user_read'
      operationId: getUsersInfo
      requestBody:
        description: List of user subjects to retrieve information
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubjectList'
            example:
              subjects:
              - 00000001-0000-0000-0000-000000000000
        required: true
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllUserResult'
              example:
                users:
                - firstName: Mike
                  lastName: Malone
                  email: mike.malone@yopmail.com
                  subject: sub1
                  status: ACTIVE
                - firstName: Steve
                  lastName: Smith
                  email: steve.smith@yopmail.com
                  subject: sub2
                  status: INACTIVE
        '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-27 12:34:50
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
      security:
      - user_store:
        - user_read
components:
  schemas:
    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
        subject:
          type: string
          description: Subject id of user
        status:
          type: string
          description: Status of user
      description: List of users' info
    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
    UserRequest:
      required:
      - email
      - firstName
      - lastName
      - subject
      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
        subject:
          type: string
          description: Subject of user
    UserCommunicationListResult:
      type: object
      properties:
        users:
          type: array
          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
      description: List of user communication data
    UsersCommunicationRequest:
      required:
      - entityId
      - spaceId
      - subjects
      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
          items:
            type: string
            description: User subjects
    AllUserResult:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserResult'
    SubjectList:
      required:
      - subjects
      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:
    user_store:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://docs.btx.banqup.com/docs/identity/auth/get-bearer-token
          scopes:
            user_read: Can read user info
            user_write: Can create new inactive users
        authorizationCode:
          authorizationUrl: https://api.btx.fr.banqup.com/v1/oauth20/authorization
          tokenUrl: https://api.btx.fr.banqup.com/v1/oauth20/token_kc
          scopes:
            user_read: Can read user info
            user_write: Can create new inactive users
