swagger: '2.0'
info:
  title: ows-users
  version: '1.0'
host: qa-ows-users.theorchard.io
basePath: /
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /auth0/users:
    get:
      tags:
      - Auth0
      summary: A proxy to [https://auth0.com/docs/api/management/v2#!/Users/get_users](https://auth0.com/docs/api/management/v2#!/Users/get_users)
      parameters:
        - in: query
          name: per_page
          type: integer
          description: Items per page, max 100.
        - in: query
          name: page
          type: integer
          description: Zero-indexed page.
      responses:
        200:
          description: |
            200 OK. See Auth0 documentation for other responses.'
    post:
      tags:
      - Auth0
      summary: Create an Auth0 user.
      parameters:
        - in: body
          name: body
          schema:
            type: object
            properties:
              email:
                type: string
                description: email for user.
              user_id:
                type: string
              name:
                type: string
              user_metadata:
                type: object
            required:
              - email
          description: Data required to create a user in auth0.
      responses:
        200:
          description: 200 ok.
        400:
          description: Email key is required or user already exists with this email.

  /auth0/users/bulk:
    get:
      tags:
      - Auth0
      summary: Get a page of Auth0 emails.
      parameters:
        - in: query
          name: auth0_ids
          type: array
          items:
            type: string
          description: query parameter array of auth0 ids
      responses:
        200:
          description: |
            200 OK.
  /auth0/recovery:
    post:
      tags:
      - Auth0
      summary: Trigger password recovery email.
      parameters:
        - in: body
          name: body
          schema:
            type: object
            properties:
              email:
                type: string
                description: the email of the user to recover password for
              connection:
                type: string
                description: the Auth0 connection to use
              client_id:
                type: string
                description: the Auth0 client generating this request
            required:
              - email
      responses:
        200:
          description: |
            200 OK.
  /auth0/send-verification-email:
    post:
      tags:
      - Auth0
      summary: Trigger Verify email.
      parameters:
        - in: body
          name: body
          schema:
            type: object
            properties:
              user_id:
                type: string
                description: Auth0 user id.
            required:
              - user_id
      responses:
        200:
          description: |
            200 OK.
  /auth0/organizations/{org_name}:
    get:
      tags:
      - Auth0
      summary: Get Auth0 organization info.
      responses:
        200:
          description: OK.
          examples:
            application/json: {
              "branding": {
                "colors": {
                  "page_background": "#17415E",
                  "primary": "#276B9B"
                },
                "logo_url": "https://qa-cdn.theorchard.io/assets/orchard/icons/brand-flat.png"
              },
              "display_name": "The Orchard",
              "id": "org_vdEfyCAGWYnTkX6G",
              "metadata": {
                "corporate_url": "https://www.theorchard.com",
                "facebook_url": "https://www.facebook.com/theorchard",
                "instagram_url": "https://www.instagram.com/the_orchard_",
                "linkedin_url": "https://www.linkedin.com/company/the-orchard",
                "twitter_url": "https://x.com/the_orchard",
                "youtube_url": "https://www.youtube.com/user/theorchardmusic"
              },
              "name": "orchard"
            }
        404:
          description: Not Found.
          examples:
            application/json: {
              "code": "not_found_error",
              "message": "No organization found by that id or name"
            }
  /users/bulk-auth0-password-reset:
    post:
      tags:
      - Auth0
      summary: Bulk password reset.
      parameters:
        - in: body
          name: body
          schema:
            type: object
            properties:
              user_ids:
                type: array
                description: Auth0 user id.
                items:
                  type: string
            required:
              - user_ids
      responses:
        200:
          description: |
            200 OK.
  /users/auth0-update:
    post:
      tags:
      - Users
      summary: Update user user_id with auth0 details.
      parameters:
        - in: body
          name: body
          schema:
            type: object
            properties:
              user_id:
                type: integer
                description: Vend contact id for now.
              user_type:
                type: string
                description: Alw for now.
              auth0_id:
                type: string
                description: auth0 unique id.
            required:
              - user_id
              - user_type
              - auth0_id
      responses:
        200:
          description: |
            200 OK.
  /users/alw/{user_id}:
    patch:
      tags:
      - Users
      summary: Patch a Vend contact User.
      parameters:
        - in: path
          name: user_id
          type: string
          required: true
      responses:
        200:
          description: |
            200 OK.
  /users/auth0/single-signon:
    post:
      tags:
      - Users
      summary: Send notification for Auth0 single sign on.
      description: Send notification for Auth0 single sign on.
      parameters:
        - in: body
          name: body
          schema:
            type: object
            properties:
              user_id:
                type: string
                description: alw:Vend contact id for now.
              auth0_id:
                type: string
                description: Auth0 user id.
              email:
                type: string
                description: auth0 user email.
            required:
              - user_id
              - auth0_id
              - email
      responses:
        200:
          description: |
            200 OK.
  /users/auth0/{auth0_id}/primary:
    put:
      tags:
      - Users
      summary: Set the primary vend contact for an auth0 user.
      description: Set the primary vend contact for an auth0 user.
      parameters:
        - in: path
          name: auth0_id
          type: string
          required: true
        - in: body
          name: body
          schema:
            type: object
            properties:
              user_id:
                type: string
                description: alw:Vend contact id for now.
              identity_id:
                type: string
                description: id of the identity associated with the auth0 user.
            required:
              - user_id
      responses:
        200:
          description: |
            200 OK.
  /users/auth0/email/{email}:
    get:
      tags:
      - Users
      summary: |
        Get user user_id with auth0 details.
      parameters:
        - in: path
          name: email
          description: Email address
          type: string
          required: true
      responses:
        200:
          description: |
            200 OK. Auth0 id was found with no issues. If no id is found, endpoint returns an empty message.
            examples:
              found:
                status: ok
                application/json: {
                  "result": [
                    "auth0|5e58f645fceb0b0c26836d75"
                  ]
                }
                description: |
                  auth0 id found for email.
              notfound:
                status: ok
                application/json: {
                  "result": []
                }
                description: |
                  no auth0 id found for this email.
  /users/{user_id}/auth0/deactivate/{app}:
    delete:
      tags:
      - Users
      summary: Deactivate a specific user contact and block in auth0 if necessary.
      description: Deactivate a specific user contact and block in auth0 if necessary.
      parameters:
        - in: path
          name: user_id
          type: string
          required: true
          description: vend_contact.id or orchardmin_user.id.
        - in: path
          name: app
          type: string
          required: true
          description: The app to deactivate for (oa, alw, ...)

      responses:
        200:
          description: |
            200 OK.
  /ws/generate-token/{token_type}:
    get:
      tags:
      - Workstation
      summary: Generate token based on a token type.
      description: |
        Generate token based on a token type. The query params are: timestamp, label_id, user_id and
        subaccount_id if we are requesting a token for a subaccount.
      parameters:
        - in: path
          name: token_type
          type: string
          required: true
        - description: Grass account type.
          in: header
          name: Grass-Account-Type
          type: string
          enum:
            - vendor
            - subaccount
          required: true
        - description: Grass account id.
          in: header
          name: Grass-Account-Id
          type: integer
          required: true
        - description: Orchard-User-id.
          in: header
          name: Orchard-User-id
          type: string
          required: true
      responses:
        200:
          description: |
            200 OK.
  /ws/generate-jwt-token/feature-fm:
    get:
      tags:
      - Workstation
      summary: Generate jwt token signed for feature-fm.
      description: Generate jwt token signed for feature-fm.
      parameters:
        - description: Grass account type.
          in: header
          name: Grass-Account-Type
          type: string
          enum:
            - vendor
            - subaccount
          required: true
        - description: Grass account id.
          in: header
          name: Grass-Account-Id
          type: integer
          required: true
        - description: Orchard-User-id.
          in: header
          name: Orchard-User-id
          type: string
          required: true
      responses:
        200:
          description: |
            200 OK.
  /ws/agreements/vendor/{permission_type_id}:
    post:
      tags:
      - Workstation
      summary: Creates a new vendor agreement.
      description: Creates a new vendor agreement.
      parameters:
        - description: Permission type id.
          in: path
          name: permission_type_id
          type: integer
          required: true
        - description: Grass account type.
          in: header
          name: Grass-Account-Type
          type: string
          enum:
            - vendor
            - subaccount
          required: true
        - description: Grass account id.
          in: header
          name: Grass-Account-Id
          type: integer
          required: true
        - description: Orchard-User-id.
          in: header
          name: Orchard-User-id
          type: string
          required: true
        - in: body
          name: body
          schema:
            type: object
            properties:
              impersonator_user_id:
                type: string
                description: impersonator orchard user id.
      responses:
        200:
          description: |
            200 OK.
    get:
      tags:
      - Workstation
      summary: Fetch a vendor agreement.
      description: Fetch a vendor agreement.
      parameters:
        - description: Permission type id.
          in: path
          name: permission_type_id
          type: integer
          required: true
        - description: Grass account type.
          in: header
          name: Grass-Account-Type
          type: string
          enum:
            - vendor
            - subaccount
          required: true
        - description: Grass account id.
          in: header
          name: Grass-Account-Id
          type: integer
          required: true
        - description: Orchard-User-id.
          in: header
          name: Orchard-User-id
          type: string
          required: true
      responses:
        200:
          description: |
            200 OK.
  /ws/agreements/vendor:
    delete:
      summary: Deletes a vendor agreement.
      description: Deletes a vendor agreement.
      parameters:
        - description: Vendor agreement id
          in: query
          name: id
          type: integer
          required: true
      responses:
        204:
          description: |
            204 OK.
            Agreeement was deleted.
        404:
          description: |
            404 Not Found.
            Agreement with supplied ID could not be found.
  /auth0/users/{user_id}:
    patch:
      tags:
      - Auth0
      summary: |
        A proxy to [https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id)
      parameters:
        - in: path
          name: user_id
          description: Auth0 user id.
          type: string
          required: true
        - in: body
          name: body
          description: JSON payload of user properties to patch.
          schema:
            type: object
      responses:
        200:
          description: |
            200 OK. See Auth0 documentation for other responses.
            If request body `blocked` is set to true, it will additionally add a `user_metadata.blocked_at` timestamp to the user object.
    get:
      tags:
      - Auth0
      summary: |
        Get an Auth0 user
      parameters:
        - in: path
          name: user_id
          description: Auth0 user id.
          type: string
          required: true
      responses:
        200:
          description: |
            200 OK.
    delete:
      tags:
      - Auth0
      summary: |
        Get an Auth0 user
      parameters:
        - in: path
          name: user_id
          description: Auth0 user id.
          type: string
          required: true
      responses:
        200:
          description: |
            200 OK.
  /auth0/reset-users/{user_identifier}:
    delete:
      tags:
      - Auth0
      summary: |
        Reset all WStation users with this auth0 id.
        This is for cucumber tests, so they can be re-used like non-migrated users.
      description: |
        Reset all WStation users with this auth0 id.
        This is for cucumber tests, so they can be re-used like non-migrated users.
      parameters:
        - in: path
          name: user_identifier
          description: User Id (oa:123 or alw:123)
          type: string
          required: true
      responses:
        200:
          description: |
            200 OK.
  /auth0/reset-mfa/{auth0_id}:
    delete:
      tags:
      - Auth0
      summary: |
        Reset all mfa devices for this auth0 id.
      description: |
        Reset all mfa devices for this auth0 id.
      parameters:
        - in: path
          name: auth0_id
          description: Auth0 user id.
          type: string
          required: true
      responses:
        200:
          description: |
            200 OK.
  /auth0/users/{auth0_id}/all-accounts:
    get:
      tags:
      - Auth0
      summary: |
        Get all accounts with this auth0_user_id.
      description: |
        Get all accounts with this auth0_user_id.
      parameters:
        - in: path
          name: auth0_id
          description: Auth0 user id.
          type: string
          required: true
        - in: query
          name: include_deleted
          type: string
          description: If exists, return deleted accounts
      responses:
        200:
          description: |
            200 OK.
  /users:
    get:
      tags:
      - Users
      summary: Get all users. Use with caution.
      parameters:
        - in: query
          name: type
          required: true
          type: string
          enum:
            - oa
          description: |
            Filter users by a certain type. Only 'oa' is supported now.
      responses:
        '200':
          description: |
            The request was successful.
          schema:
            type: object
            properties:
              items:
                $ref: '#/definitions/ArrayOfUsers'
        '400':
          description: |
            The request was invalid.
        '403':
          description: |
            The request was forbidden. A user with Grass-Account-Type
            'vendor' or 'subaccount' is not allowed to look up oa users.
            This could also be from an inconsistent request information.
        '404':
          description: |
            The requested resource was not found.
      description: |
        Returns the user's type and account information.
  /users/{user_id}:
    get:
      tags:
      - Users
      summary: |
        Returns the user's type and account information.
      parameters:
        - in: path
          name: user_id
          required: true
          type: string
          description: This is the Orchard-User-Id
      responses:
        '200':
          description: |
            The request was successful.
          examples:
            oa:
              type: oa
              user_id: oa:123
              first_name: Alfred
              last_name: Hitchcock
              email: ahitchcock@theorchard.com
              account:
                vendor_id: null
                subaccount_id: null
              active: Y
            vendor:
              type: alw
              user_id: alw:16088
              first_name: Jerome David
              last_name: Salinger
              email: jsalinger@theorchard.com
              account:
                vendor_id: 7123
                subaccount_id: null
              language: en
              active: N
              default_brand: orchard
            subaccount:
              type: alw
              user_id: alw:49283
              first_name: George
              last_name: Gershwin
              email: ggershwin@theorchard.com
              account:
                vendor_id: 21449
                subaccount_id: 30492
              language: en
              active: N
              default_brand: orchard
        '400':
          description: |
            The request was invalid.
        '403':
          description: |
            The request was forbidden. This could be from inconsistent request information.
        '404':
          description: |
            The requested resource was not found.
  /users/get-alw-users-by-email:
    get:
      tags:
      - Users
      parameters:
        - in: query
          name: email
          required: true
          type: string
          description: This is the email for a Workstation user
      responses:
        '200':
          description: |
            The request was successful.
          schema:
            type: array
            items:
              type: object
              properties:
                email:
                  type: string
                  example: email@test.com
                user_id:
                  type: integer
                  example: 123
                vendor_id:
                  type: integer
                  example: 456
        '400':
          description: |
            The query parameter was invalid.
        '404':
          description: |
            The requested resource was not found.
      summary: |
        Returns workstation user(s) info based on email.
  /ows/{account_type}/{account_id}/primary-contact:
    get:
      tags:
      - Users
      parameters:
        - in: path
          name: account_type
          required: true
          type: string
          description: The type of account the user belongs to.
          enum:
            - vendor
            - subaccount
        - in: path
          name: account_id
          required: true
          type: string
          description: The ID of the vendor or subaccount.
        - in: query
          name: active
          required: false
          type: string
          description: The "active" status of the vendor contact.
      responses:
        200:
          description: |
            The request was successful.
          examples:
            application/json: {
              "type": "alw",
              "user_id": "alw:123",
              "account": {
                "vendor_id": 1234,
                "subaccount_id": 5656
              },
              "login": "login139",
              "language": "en",
              "auth0_user_id": "auth0139",
              "primary": None,
              "active": "Y",
              "contact_id": 4444,
              "first_name": "first name",
              "last_name": "last name",
              "email": "email",
              "requested_login_email": ""
            }
        404:
          description: 404 Not found
          examples:
            application/json: {
                "code": "not_found_error",
                "message": "User not found."
            }
        500:
          description: 500 Internal server error
          examples:
            application/json: {
                "code": "internal_error",
                "message": null
            }
      summary: |
        Return the contact information for the primary user for an account
  /users/{user_id}/session/{app}:
    get:
      tags:
      - Users
      parameters:
        - in: path
          name: user_id
          required: true
          type: string
          description: This is either `orchadmin_users.id` or `vend_contact.id`.
        - in: path
          name: app
          required: true
          type: string
          description: This will be 'oa' or 'alw' for now, but other apps can follow.
      responses:
        '200':
          description: |
            The request was successful.
          examples:
            oa:
              Oa:
                VECTORAPI_ACCESS_TOKEN: 481db93f2d9016dd736a001619c70ec5
                VECTORAPI_REFRESH_TOKEN: d630803a4a928a147d52ff7b8a8dd38d
              S_OA_OWNER: orchard
              S_USERID: '1043'
              S_LOGINIP: 192.168.32.124
              S_F_NAME: Rishi
              S_L_NAME: Satsangi
              S_PRIMARY_ROLE: Engineering
              S_PRIMARY_ROLE_ID: '1'
              S_ROLES: '1,7,8,10,24,29'
              S_PERMISSIONS: '43,44,45,46,47,48,49,150,151,181,182,183,258,259,262,252,242,243,2,3,4,5,6,7,8,9,246,247,248,249,250,253,254,255,217,218,219,171,203,204,205,206,207,208,315,316,209,210,211,212,222,223,232,233,154,326,239,240,241,228,229,230,277,278,279,280,281,282,244,197,198,199,213,214,291,292,293,294,29,30,31,58,306,155,50,51,52,53,54,55,200,201,202,321,322,327,328,320,175,260,261,276,32,33,34,35,36,37,38,39,40,41,42,56,57,59,62,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,173,174,234,235,236,237,238,265,266,269,307,310,300,301,309,156,157,158,159,267,10,11,12,13,14,311,312,317,160,286,295,231,177,178,179,196,225,226,256,257,251,188,161,162,163,164,165,166,167,170,168,169,15,16,17,18,19,20,21,22,23,24,25,26,27,28,60,61,63,64,65,66,67,68,69,70,128,129,130,131,132,133,134,172,176,220,221,263,264,270,271,274,275,287,288,289,290,296,297,302,303,304,305,308,313,314,318,323,324,325,283,284,285,227,189,190,191,192,193,194,195,245,272,273,215,216,332,333,334,335,336,337,338,339,340,341,342,343,344,319,1'
              S_DAYS_LEFT_BEFORE_EXPIRATION: '62'

            alw:
              id: 123
              vendor:
                company: Pizza Records
                language: en
                owner: kdigital
                is_distributor: 'N'
                number_format: us
                name: Rick Moranis
                label_identifier: Frontline
                vendor_id: 1234
              vend_contact_roles:
                - role:
                    role: Administrator
                    vendor_role_permissions:
                      - role_id: 4
                        permission:
                          resource:
                            resource: releasebuilder
                            id: 1
                          id: 36
                          privilege: null
                        allow: 'Y'
                        id: 1
                      - role_id: 4
                        permission:
                          resource:
                            resource: account
                            id: 9
                          id: 47
                          privilege:
                            id: 16
                            privilege: manageusers
                        allow: 'Y'
                        id: 2
                    id: 4
                  vend_contact_id: 123
                  id: 1
                - role:
                    role: Accounting
                    vendor_role_permissions:
                      - role_id: 5
                        permission:
                          resource:
                            resource: releasebuilder
                            id: 1
                          id: 36
                          privilege: null
                        allow: 'N'
                        id: 3
                      - role_id: 5
                        permission:
                          resource:
                            resource: account
                            id: 9
                          id: 47
                          privilege:
                            id: 16
                            privilege: manageusers
                        allow: 'N'
                        id: 4
                      - role_id: 5
                        permission:
                          resource:
                            resource: legal
                            id: 19
                          id: 183
                          privilege:
                            id: 167
                            privilege: terms
                        allow: 'Y'
                        id: 5
                    id: 5
                  vend_contact_id: 123
                  id: 2
              contact:
                contact_email: test@test.com
                contact_id: 4444
              login: pizzaman
              subaccount:
                subaccount_name: El Subaccount
                subaccount_id: 5656
        '400':
          description: |
            The request was invalid.
        '404':
          description: |
            The user_id or application does not exist.
      summary: (DEPRECATED) use /users/session/{app} instead....Returns a JSON object in the session shape for the specified app, OA (oa) or Workstation (alw)
      description: |
        Returns a JSON object in the session shape for the specified app, OA (oa) or Workstation (alw). For oa and alw, these will be in the shape of the respective $_SESSION objects containing role and permission information. Other apps could have different shapes.
  /users/{user_id}/session/{app}/raw:
    get:
      tags:
      - Users
      parameters:
        - in: path
          name: user_id
          required: true
          type: string
          description: This is either `orchadmin_users.id` or `vend_contact.id`.
        - in: path
          name: app
          required: true
          type: string
          description: This will be 'oa' or 'alw' for now, but other apps can follow.
      responses:
        '200':
          description: |
            The request was successful.
        '400':
          description: |
            The request was invalid.
        '404':
          description: |
            The user_id or application does not exist.
      summary: (DEPRECATED) use /users/session/{app} instead....Get user session metadata for an app using raw SQL.
      description: |
        Get user session metadata for an app using raw SQL.
  /users/{user_id}/session/{app}/linked-accounts:
    get:
      tags:
      - Users
      parameters:
        - in: path
          name: user_id
          required: true
          type: string
          description: This is either `orchadmin_users.id` or `vend_contact.id`.
        - in: path
          name: app
          required: true
          type: string
          description: This will be 'oa' or 'alw' for now, but other apps can follow.
      responses:
        '200':
          description: |
            The request was successful.
        '400':
          description: |
            The request was invalid.
        '404':
          description: |
            The user_id or application does not exist.
      summary: Get this user's linked account details.
      description: |
        Get this user's linked account details.
  /hello:
    get:
      tags:
      - Health
      responses:
        '200':
          examples:
            success:
              status: ok
          description: |
            Application is operational.
      summary: Health check for the ows-users microservice.
  /users/{user_id}/status:
    put:
      tags:
      - Users
      summary: Update user status.
      parameters:
        - description: Id of the vend_contact to be updated
          in: path
          name: user_id
          required: true
          type: integer
        - description: Grass account type.
          in: header
          name: Grass-Account-Type
          type: string
          enum:
            - vendor
            - subaccount
          required: true
        - description: Grass account id.
          in: header
          name: Grass-Account-Id
          type: integer
          required: true
        - in: body
          name: body
          schema:
            $ref: '#/definitions/user-status-put-body'
      responses:
        200:
          description: 200 OK
          examples:
            application/json: {
                "type": "alw",
                "user_id": "alw:12345",
                "account": {
                    "vendor_id": 123,
                    "subaccount_id": 1
                },
                "login": "test",
                "language": "en",
                "auth0_user_id": null,
                "primary": null,
                "active": "N",
                "contact_id": 1234
            }
        400:
          description: 400 Bad Request
          examples:
            "message": Data should contain active field with value "Y" or "N".
        404:
          description: 404 Not found
          examples:
            application/json: {
                "code": "not_found_error",
                "message": null
            }
        500:
          description: 500 Internal server error
          examples:
            application/json: {
                "code": "internal_error",
                "message": null
            }
  /users/document:
    get:
      tags:
      - Users
      summary: |
        Returns a document for cloudsearch user corpus containing list of user/s info belonging to contact_id / user_id / subaccount_id
      parameters:
        - in: query
          name: contact_id
          type: integer
          description: unique identifier for a contact
        - in: query
          name: user_id
          type: integer
          description: unique identifier for a vend_contact
        - in: query
          name: subaccount_id
          type: integer
          description: unique identifier for a subaccount
      responses:
        200:
          description: 200 OK
          examples:
            application/json: [
             {
              "contact_first_name": "test",
              "contact_last_name": "user",
              "contact_email": "testuser@theorchard.com",
              "vendor_id": 1,
              "user_id": 2,
              "is_active": 1,
              "subaccount": "testsubaccount",
              "master": "N",
              "permissions": "Accounting,Analytics",
              "subaccount_id": 3
             },
             {
              "contact_first_name": "test",
              "contact_last_name": "contact",
              "contact_email": "testcontact@theorchard.com",
              "vendor_id": 1,
              "user_id": 3,
              "is_active": 0,
              "subaccount": "testsubaccount",
              "master": "N",
              "permissions": "Accounting",
              "subaccount_id": 3
             }
            ]
        404:
          description: 404 Not found
          examples:
            application/json: {
                "code": "not_found_error",
                "message": null
            }
  /{account_type}/{account_id}/users:
    get:
      tags:
      - Users
      parameters:
        - in: path
          name: account_type
          required: true
          type: string
          description: The type of account the authenticated user belongs to.
          enum:
            - vendor
            - subaccount
        - in: path
          name: account_id
          required: true
          type: string
          description: The Id of the authenticated user.
        - description: Grass account type.
          in: header
          name: Grass-Account-Type
          type: string
          enum:
            - vendor
            - subaccount
          required: true
        - description: Grass account id.
          in: header
          name: Grass-Account-Id
          type: integer
          required: true
        - description: Orchard-User-id.
          in: header
          name: Orchard-User-id
          type: string
          required: true
        - in: query
          name: status
          type: string
          description: optional query param. status=disable to get deactivated users
      responses:
        200:
          description: |
            The request was successful.
          examples:
            Returns the list of users with associated contact information:
              items:
                - user_id: 123
                  contact_first_name: Alfred
                  contact_last_name: Hitchcock
                  contact_email: ahitchcock@theorchard.com
                  subaccount: subaccount
                  permissions: Administrator
                  is_active: 1
                  date_deleted: "2017-11-16 01:26:32"
              pagination:
                type: standard
                count: 1,
                page_offset: 0,
                page_limit: 50
        404:
          description: 404 Not found
          examples:
            application/json: {
                "code": "not_found_error",
                "message": null
            }
        500:
          description: 500 Internal server error
          examples:
            application/json: {
                "code": "internal_error",
                "message": null
            }
      summary: |
        Return list of users and associated contact information
  /users/{user_id}/minimum-details:
    get:
      tags:
      - Users
      parameters:
        - in: path
          name: user_id
          required: true
          type: string
          description: The user id.
        - description: Grass account type.
          in: header
          name: Grass-Account-Type
          type: string
          enum:
            - vendor
            - subaccount
          required: true
        - description: Grass account id.
          in: header
          name: Grass-Account-Id
          type: integer
          required: true
        - description: Orchard-User-id.
          in: header
          name: Orchard-User-id
          type: string
          required: true
        - in: query
          name: include_roles
          type: string
          description: if a value exists, the roles should be included
      responses:
        200:
          description: |
            The request was successful.
          examples:
            Returns the list of users with associated contact information:
              items:
                - user_id: 123
                  contact_first_name: Alfred
                  contact_last_name: Hitchcock
                  contact_email: ahitchcock@theorchard.com
                  subaccount: subaccount
                  permissions: Administrator
                  is_active: 1
                  date_deleted: "2017-11-16 01:26:32"
              pagination:
                type: standard
                count: 1,
                page_offset: 0,
                page_limit: 50
        404:
          description: 404 Not found
          examples:
            application/json: {
                "code": "not_found_error",
                "message": null
            }
        500:
          description: 500 Internal server error
          examples:
            application/json: {
                "code": "internal_error",
                "message": null
            }
      summary: |
        Return list of users and associated contact information
  /users/verify-login:
    post:
      tags:
      - Users
      parameters:
        - in: body
          name: body
          description: extra metadata for that user.
          schema:
            type: object
            properties:
              login:
                type: string
              password:
                type: string
              feature:
                type: string
                description: Optional) Feature flag name to get its status.
            required:
              - login
              - password
      responses:
        200:
          description: |
            The request was successful.
      summary: |
        Return details for user with matching login and password.
      description: |
        Return details for user with matching login and password.
  /users/identity/{orchard_identity}/application/{app_name}/profiles:
    get:
      tags:
      - Profiles
      summary: Get all profiles for this auth0 user for this application. Along with profiles it will also send roles allowed so no need to make separate call.
      parameters:
        - in: path
          name: orchard_identity
          required: true
          type: string
          description: Auth0 user identifier for now.
        - in: path
          name: app_name
          required: true
          type: string
          description: Application that the user is trying to access eg Workstation, OrchardGo, Royalty etc.
        - in: query
          name: types
          type: string
          required: false
          description: comma-delimited list of profile types to return (overrides application defaults -- be careful)
      responses:
        200:
          description: 200 OK
          examples:
            application/json:
              {
                "items": [
                {
                  "profile_type": "SettingsProfile",
                  "profile_name": "artistozuna_profile1",
                  "profile_id": 1346777,
                  "roles": [
                    "analytics"
                  ]
                },
                {
                  "profile_type": "InsightsProfile",
                  "profile_name": "frenchkiss-vc",
                  "profile_id": 6918,
                  "roles": [
                    "analytics",
                    "catalog",
                    "accounting"
                  ]
                }
                ],
                "pagination": {
                  "type": "none",
                  "total_records": 2
                }
              }
  /users/identity/{identity_id}/applications:
    get:
      tags:
      - Applications
      summary: Get all applications this identity has access to backed by a Profile.
      parameters:
        - in: header
          name: Orchard-Profile-Type
          required: true
          type: string
          description: profile type of accessing Identity. Part of the Orchard standard Profile context type.
        - in: header
          name: Orchard-Profile-Id
          required: true
          type: string
          description: profile id of accessing Identity. Part of the Orchard standard Profile context type.
        - in: path
          name: identity_id
          required: true
          type: string
          description: uuid format.
        - in: query
          name: role
          required: false
          type: string
          description: Optional query parameter to retrieve only applications where identity has certain role.
        - in: query
          name: resource_type
          required: false
          type: string
          description: Optional query parameter to retrieve only applications for specific resource. Mutually required with "resource_uuid".
        - in: query
          name: resource_uuid
          required: false
          type: string
          description: Optional query parameter to retrieve only applications for specific resource. Mutually required with "resource_type".
        - in: query
          name: brand
          required: false
          type: string
          description: Optional query parameter to override brand for applications.
      responses:
        200:
          description: 200 OK
          examples:
            application/json:
             {
                "items": [
                  {
                    "name": "Workstation",
                    "id": "workstation",
                    "url": "https://workstation.qaorch.com",
                    "updated_on": "2020-11-19T21:12:07.372000000Z",
                    "updated_by": "kinesis-to-neo4j",
                    "roles": ['analytics', 'catalog'],
                  },
                  {
                    "name": "Settings",
                    "id": "settings",
                    "url": "https://settings.qaorch.com",
                    "updated_on": null,
                    "updated_by": null,
                    "roles": []
                  },
                  {
                    "name": "Insights",
                    "id": "insights",
                    "url": "https://insights.qaorch.com",
                    "updated_on": null,
                    "updated_by": null,
                    "roles": ['administrator']
                  }
                ]
              }
  /profile/identity/{identity_id}:
    post:
      tags:
      - Profiles
      summary: Create a new Profile node and link it to the given Identity, so that Identity->HAS_PROFILE->Profile.
      parameters:
        - in: path
          name: identity_id
          required: true
          type: string
          description: Auth0 user id.
        - in: body
          name: data
          required: true
          description: The payload
          schema:
            type: object
            properties:
              profile_id:
                type: integer
                description: the unique id for this profile. if one is not provided, it will be assigned an auto-increment id.
                example: 45556789
              profile_name:
                type: string
                example: 'Test Profile'
              profile_type:
                type: string
                description: The type of profile (LabelProfile, ArtistProfile, etc)
                example: 'ArtistProfile'
              roles:
                type: array
                items:
                  type: string
                  example: ['analytics', 'catalog']
      responses:
        201:
          description: 201 Created
          examples:
            application/json:
              {
                profile_name: 'Test Profile',
                profile_type: 'ArtistProfile',
                profile_id: 555,
                roles : [ "catalog", "analytics"]
              }
        404:
          description: 404 Not Found
          examples:
            application/json:
              {
                code: 'not_found_error',
                message: 'Identity does not exist.'
              }
        400:
          description: 404 Bad Request
          examples:
            application/json:
              {
                code: 'validation_error',
                message: {
                  'profile_name': [
                      'Missing data for required field.'],
                  'profile_type': [
                      'Missing data for required field.']}
              }
  /users/identity/{identity_id}/vendor/{label_profile_id}:
    get:
      summary: Returns vendor information associated with a label profile.
      parameters:
        - in: path
          name: identity_id
          required: true
          type: string
          description: Identity uuid.
        - in: path
          name: label_profile_id
          required: true
          type: integer
          description: Label profile id or vendor contact id
      responses:
        '200':
          description: OK
        '404':
            examples:
             default:
               message: null
               code: "not_found_error"
            description: Vendor information not found for the given identity / label profile.
  /users/identity/{identity_id}/label-profile-access/{label_profile_id}:
    get:
      summary: Check if an identity has active access to a LabelProfile.
      description: >
        Mirrors the query that fills the Workstation account switcher dropdown
        (linked label profiles with active vendor access), so the auth0
        account-switch action can rely on a single source of truth.
      parameters:
        - in: path
          name: identity_id
          required: true
          type: string
          description: Identity uuid.
        - in: path
          name: label_profile_id
          required: true
          type: integer
          description: LabelProfile profileId (vend_contact id).
      responses:
        '200':
          description: OK
          examples:
            application/json:
              has_access: true
  /profile/profile_id/{profile_id}/profile_type/{profile_type}:
    get:
      tags:
      - Profiles
      summary: Get a Profile by type and id.
      parameters:
      - in: path
        name: profile_id
        required: true
        type: string
        description: The id of the Profile.
      - in: path
        name: profile_type
        required: true
        type: string
        description: The type of the Profile (e.g. ArtistProfile, LabelProfile).
      responses:
        200:
          description: 200 profile with type and id was found
          examples:
            application/json:
              {
                'profile_id': 555,
                'profile_name': 'Updated Profile Name',
                'profile_type': 'ArtistProfile',
                'roles': [
                    'catalog',
                    'analytics'
                ]
              }
        404:
          description: Profile with type and id not found.
          examples:
            application/json:
              {
                code: 'not_found_error',
                message: 'Profile not found'
              }
    delete:
      tags:
      - Profiles
      summary: Delete a Profile by type and id.
      parameters:
      - in: path
        name: profile_id
        required: true
        type: string
        description: The id of the Profile.
      - in: path
        name: profile_type
        required: true
        type: string
        description: The type of the Profile (e.g. ArtistProfile, LabelProfile).
      responses:
        204:
          description: 204 deleted, no content
        404:
          description: Profile with type and id not found.
          examples:
            application/json:
              {
                code: 'not_found_error',
                message: 'Profile not found'
              }
    patch:
      tags:
      - Profiles
      summary: Patch a Profile by id and type
      parameters:
      - in: path
        name: profile_id
        required: true
        type: string
        description: The id of the Profile.
      - in: path
        name: profile_type
        required: true
        type: string
        description: The type of the Profile (e.g. ArtistProfile, LabelProfile).
      responses:
        200:
          description: 200 ok, updated
          examples:
            application/json:
              {
                profile_name: 'Updated Profile',
                profile_type: 'ArtistProfile',
                profile_id: 555,
                roles : ['catalog', 'analytics']
              }
        400:
          description: 400 validation error
          examples:
            application/json:
              {
                code: 'validation_error',
                message: {
                  'profile_name': [
                      'Not a valid string.'],
                  'roles': [
                      'Not a valid list.'],
                  'profile_type': [
                      'Invalid enum member pizza']}
                }
        404:
          description: 404 profile not found
          examples:
            application/json:
              {
                code: 'not_found_error',
                message: 'Profile not found'
              }
  /users/identity:
    post:
      tags:
      - Identities
      summary: Create an identity node in graphdb.
      parameters:
        - in: body
          name: data
          description: the payload
          required: true
          schema:
            type: object
            properties:
              identity_id:
                type: string
                description: auth0 identity id associated with identity node.
              email:
                type: string
                description: email associated with the identity node.
              name:
                type: string
                description: full name of user associated with the identity node.
      responses:
        200:
          description: 200 OK
          examples:
            application/json:
              {
                identity_id: '123',
                email: 'test@theorchard.com',
                name: 'test'
              }
        500:
          description: 500 internal error
          examples:
            application/json:
              {
                'code': 'internal_error',
                'message': 'Neo4j is not ready.'
              }
        400:
          description: 400 bad request
          examples:
            application/json:
              [{
                'code': 'validation_error',
                'message': {
                  'identity_id': [
                    'Missing data for required field.']}
              },
              {
                'code': 'already_exists',
                'message': 'Identity already exists.'
              }]
  /users/identity/{identity_id}:
    get:
      tags:
      - Identities
      summary: Get an identity from the graphdb.
      parameters:
        - in: path
          name: identity_id
          required: true
          type: string
          description: auth0 identity id.
      responses:
        200:
          description: 200 OK
          examples:
            application/json:
              {
                identity_id: 123,
                email: 'test@theorchard.com',
                name: 'test'
              }
        500:
          description: 500 internal error
          examples:
            application/json:
              {
                'code': 'internal_error',
                'message': 'Neo4j is not ready.'
              }
        404:
          description: 404 not found
          examples:
            application/json:
              {
                'code': 'not_found_error',
                'message': 'Identity not found'
              }
    patch:
      tags:
      - Identities
      summary: Update an identity in the graphdb.
      parameters:
        - in: path
          name: identity_id
          required: true
          type: string
          description: auth0 identity id.
        - in: body
          name: data
          description: the payload
          required: true
          schema:
            type: object
            properties:
              email:
                type: string
                description: email associated with the identity node.
              name:
                type: string
                description: full name of user associated with the identity node
              localization:
                type: string
                description: ISO language code
      responses:
        200:
          description: 200 OK
          examples:
            application/json:
              {
                  'identity_id': '123',
                  'email': 'test@theorchard.com',
                  'name': 'test@theorchard.com'
              }
        400:
          description: 400 bad request
          examples:
            application/json:
              {
                'code': 'validation_error',
                'message': {'identity_id': ['Missing data for required field.']}
              }
        404:
          description: 404 not found
          examples:
            application/json:
              {
                'code': 'not_found_error',
                'message': 'Identity not found'
              }
        500:
          description: 500 internal error
          examples:
            application/json:
              {
                'code': 'internal_error',
                'message': 'Neo4j is not ready.'
              }
    delete:
      tags:
      - Identities
      summary: Delete an identity and all its relationships in graphdb.
      parameters:
        - in: path
          name: identity_id
          required: true
          type: string
          description: auth0 identity id.
      responses:
        204:
          description: 204 OK
          examples:
            applicaton/json:
              {
                None
              }
        404:
          description: 404 not found
          examples:
            application/json:
              {
                'code': 'not_found_error',
                'message': 'Identity not found'
              }
        500:
          description: 500 internal error
          examples:
            application/json:
              {
                'code': 'internal_error',
                'message': 'Neo4j is not ready.'
              }
  /users/identity/{identity_id}/device:
    post:
      tags:
      - User devices
      summary: Add a user device to identity.
      parameters:
        - in: path
          name: identity_id
          required: true
          type: string
          description: auth0 identity id.
        - in: body
          name: data
          description: the payload
          required: true
          schema:
            type: object
            properties:
              push_token:
                type: string
                description: push notification token for that device.
              platform_type:
                type: string
                description: platform of device i.e. android or ios.
              device_id:
                type: string
                description: unique identifier of device
              localization:
                type: string
                description: ISO language code
      responses:
        200:
          description: 200 OK
          examples:
            application/json:
              {
                push_token: '123-abcd',
                platform_type: 'ios'
              }
        500:
          description: 500 internal error
          examples:
            application/json:
              {
                'code': 'internal_error',
                'message': 'Neo4j is not ready.'
              }
        400:
          description: 400 bad request
          examples:
            application/json:
              [{
                 'code': 'validation_error',
                 'message': {
                   'platform_type': ['Invalid enum member dummy']
                 }
               }]
    get:
      tags:
      - User devices
      summary: Get devices for an identity.
      parameters:
        - in: path
          name: identity_id
          required: true
          type: string
          description: auth0 identity id.
      responses:
        200:
          description: 200 OK
          examples:
            application/json:
              [{
                endpoint_arn: 'test-arn',
                push_token: '123-abcd',
                platform_type: 'ios'
              },
              {
                endpoint_arn: 'test-arn2',
                push_token: '456-abcd',
                platform_type: 'android'
              }]
        500:
          description: 500 internal error
          examples:
            application/json:
               {
                 'code': 'internal_error',
                 'message': 'Neo4j is not ready.'
               }
  /users/identity/{identity_id}/device/{device_id}:
    delete:
      tags:
        - User devices
      summary: Remove user device from an identity.
      parameters:
        - in: path
          name: identity_id
          required: true
          type: string
          description: auth0 identity id.
        - in: path
          name: device_id
          required: true
          type: string
          description: Device identifier.
      responses:
        204:
          description: delete success
        404:
          description: identity device relationship not found
        500:
          description: unexpected internal server error
  /identities/{identity_id}/application-access/{app_name}:
    get:
      tags:
        - Identities
      summary: Check if identity has access to auth0 application.
      parameters:
        - in: path
          name: identity_id
          required: true
          type: string
          description: identity id.
        - in: path
          name: app_name
          required: true
          type: string
          description: Application that the user is trying to access (e.g. seat)
      responses:
        200:
          description: Success
          examples:
            application/json:
              {
                'has_access': false
              }
        403:
          description: Unauthorized
          examples:
            application/json:
              {
                'code': 'access_check_error',
                'message': 'Failed to get roles for identity <identity_id>: <PDP error details>'
              }
        422:
          description: Invalid app_name provided
          examples:
            application/json:
              {
                'code': 'access_check_error',
                'message': 'Invalid application name'
              }
  /profile/profile_id/{profile_id}/profile_type/{profile_type}/identity:
    get:
      tags:
        - Identities
      summary: Get identity from graph for profile with profile_id and profile_type.
      parameters:
        - in: path
          name: profile_id
          required: true
          type: integer
          description: The id of the Profile.
        - in: path
          name: profile_type
          required: true
          type: string
          description: The type of the Profile (e.g. InsightsProfile, LabelProfile).
      responses:
        200:
          description: 200 success
          examples:
            application/json:
              {
                'id': '123',
                'email': 'test@theorchard.com',
                'name': 'test@theorchard.com'
              }
        404:
          description: 404 not found
          examples:
            application/json:
              {
                'code': 'not_found_error',
                'message': 'Identity not found'
              }
        500:
          description: 500 internal error
          examples:
            application/json:
              {
                'code': 'internal_error',
                'message': 'Neo4j is not ready.'
              }
  /users/identity/email/{email}:
    get:
      tags:
        - Identities
      summary: Get identity by email.
      parameters:
        - in: path
          name: email
          required: true
          type: string
          description: The email of the identity.
      responses:
        200:
          description: 200 success
          examples:
            application/json:
              {
                'id': '123',
                'email': 'test@theorchard.com',
                'name': 'test@theorchard.com'
              }
        404:
          description: 404 not found
          examples:
            application/json:
              {
                'code': 'not_found_error',
                'message': 'Identity not found'
              }
        500:
          description: 500 internal error
          examples:
            application/json:
              {
                'code': 'internal_error',
                'message': 'Neo4j is not ready.'
              }
    patch:
      tags:
        - Identities
      summary: Update existing identity node by email.
      parameters:
        - in: path
          name: email
          required: true
          type: string
          description: The email of the identity.
      responses:
        200:
          description: 200 success
          examples:
            application/json:
              {
                'id': '123',
                'email': 'test@theorchard.com',
                'name': 'test@theorchard.com'
              }
        404:
          description: 404 not found
          examples:
            application/json:
              {
                'code': 'not_found_error',
                'message': 'Identity not found'
              }
        500:
          description: 500 internal error
          examples:
            application/json:
              {
                'code': 'internal_error',
                'message': 'Neo4j is not ready.'
              }
  /users/identity/email/{email}/valid-invitation:
    get:
      tags:
        - Identities
      summary: Check if email has a valid Auth0 invitation.
      description: Validates whether the provided email has an active Auth0 invitation. Returns false if the invitation has expired (after 7 days) or does not exist.
      parameters:
        - in: path
          name: email
          required: true
          type: string
          description: The email address to check for valid invitation.
      responses:
        200:
          description: 200 success
          examples:
            application/json:
              {
                'valid': true
              }
        400:
          description: 400 bad request
          examples:
            application/json:
              {
                'code': 'invalid_email_format',
                'message': 'Invalid email format provided'
              }
        500:
          description: 500 internal error
          examples:
            application/json:
              {
                'code': 'auth0_service_error',
                'message': 'Unable to connect to Auth0 service'
              }
  /auth0/users/{user_id}/picture:
    get:
      tags:
        - Auth0
      summary: Fetch an Auth0 user picture by auth0 user_id. If the user does not exist, cache their picture as empty string.
      parameters:
        - in: path
          name: user_id
          required: true
          type: string
          description: auth0 user id.
      responses:
        200:
          description: 200 success
          examples:
            application/json:
              {
                'picture': 'http://picture.jpg'
              }
  /users/session/{app}:
    get:
      tags:
        - Users
      summary: Get user session metadata for an app using grass headers.
      parameters:
        - in: path
          name: app
          required: true
          type: string
          description: the app to fetch session metadata for (oa or alw)
        - in: header
          name: Grass-Account-Type
          required: true
          type: string
          enum:
            - vendor
            - subaccount
        - in: header
          name: Grass-Account-Id
          required: true
          type: integer
        - in: header
          name: Orchard-User-Id
          required: true
          type: string
      responses:
        200:
          description: 200 success. Language and number_format are pulled from AR for this response.
          examples:
            application/json:
              {
                "language": "en",
                "subaccount": Null,
                "contact": {},
                "number_format": "us",
                "vend_contact_roles": [],
                "vendor": {
                  "vendor": "info",
                  "company_brand": {},
                  "service_tier": {}
                },
                "identity": {},
              }
  /users/roles/{app}:
    get:
      tags:
        - Users
      summary: Get user roles for an app user. Used when calling from another microservice that has already been through grass.
      parameters:
        - in: path
          name: app
          required: true
          type: string
          description: The app to fetch roles for (oa or alw).
        - in: header
          name: Orchard-User-Id
          required: true
          type: string
        - in: header
          name: Grass-Account-Id
          required: true
          type: integer
        - in: header
          name: Grass-Account-Type
          required: true
          type: string
      responses:
        200:
          description: 200 success
          examples:
            application/json:
              {
                "role_ids": [3],
                "role_names": ["Analytics"]
              }
        400:
          description: bad request
          examples:
            application/json:
              {
                "code": "INVALID_APP",
                "message": "Invalid app."
              }
  /ws/users/roles/{user_id}:
    get:
      tags:
        - Workstation
      summary: Get user roles for vend_contact users for neo4j sync.
      parameters:
        - in: path
          name: user_id
          required: true
          type: integer
      responses:
        200:
          description: 200 success
          examples:
            application/json:
              {
                "role_ids": [3],
                "role_names": ["Analytics"]
              }
  /users/identity/{identity_id}/profile/{profile_type}/{profile_id}:
    post:
      tags:
        - Identities
      summary: Link an existing identity to an existing profile.
      parameters:
        - in: path
          name: identity_id
          required: true
          type: string
          description: Unique identity identifier.
        - in: path
          name: profile_type
          required: true
          type: string
          description: Type of profile (ex. InsightsProfile, LabelProfile)
        - in: path
          name: profile_id
          required: true
          type: integer
          description: profile identifier
      responses:
        200:
          description: 200 success
        400:
          description: bad request
          examples:
            application/json:
              {
                "code": "already_exists",
                "message": "Relationship already exists."
              }
        404:
          description: not found
          examples:
            application/json:
              {
                "code": "not_found_error",
                "message": "Profile not found"
              }
    delete:
      tags:
        - Identities
      summary: Delete an existing identity to profile relationship.
      parameters:
        - in: path
          name: identity_id
          required: true
          type: string
          description: Unique identity identifier.
        - in: path
          name: profile_type
          required: true
          type: string
          description: Type of profile (ex. InsightsProfile, LabelProfile)
        - in: path
          name: profile_id
          required: true
          type: integer
          description: profile identifier
      responses:
        204:
          description: success
        500:
          description: internal error
          examples:
            application/json:
              {
                "code": "internal_error",
                "message": "Failed to delete relationship. Please check if relationship between both nodes exist."
              }
  /users/product_managers:
    get:
      tags:
      - Users
      summary: Get all users with role product_manager.
      parameters:
        - description: Grass account type.
          in: header
          name: Grass-Account-Type
          type: string
          required: true
        - description: Grass account id.
          in: header
          name: Grass-Account-Id
          type: integer
          required: true
      responses:
        '200':
          description: |
            The request was successful.
          schema:
            type: object
            properties:
              items:
                type: object
                properties:
                  user_id:
                    type: string
                    example: 123
                  type:
                    type: string
                    example: oa
                  full_name:
                    type: string
                    example: Alfred Hitchcock
                  email:
                    type: string
                    example: ahitchcock@theorchard.com
                  active:
                    type: string
                    enum:
                      - Y
                      - N
        '400':
          description: |
            The request was invalid.
        '403':
          description: |
            The request was forbidden.
        '404':
          description: |
            The requested resource was not found.
      description: |
        Returns the Product Managers account information.
  /users/account_managers:
    get:
      summary: Return list of account managers from orchadmin_users table.
      responses:
        '200':
          description: OK
        '404':
            examples:
             default:
               message: null
               code: "not_found_error"
            description: No account managers were returned.
  /internal/users:
    get:
      tags:
        - Internal
      summary: Search for employees by search term.
      description: Returns a list of employees matching the search term.
      parameters:
        - in: query
          name: term
          required: true
          type: string
          description: Search term to find employees. Supports alphanumeric characters, spaces, hyphens, underscores, periods, at signs, and accented characters.
      responses:
        '200':
          description: Success
          schema:
            type: object
            properties:
              users:
                type: array
                items:
                  type: string
                  description: User identifier
          examples:
            application/json:
              {
                "users": ["60e196d8-2fc9-4989-9cee-03f477c2f7cd", "aa78324b-23bd-4aff-8213-e5ca5f4a3605"]
              }
        '400':
          description: Bad request - search term is required or invalid
          examples:
            application/json:
              {
                "message": "Search term is required"
              }
        '401':
          description: Unauthorized - missing or invalid JWT token
  /internal/user/get_by_email:
    post:
      tags:
        - Internal
      summary: Find employee identity by email address.
      description: |
        Search for an existing employee identity by email address.
        Used for the SEAT employee invitation flow.
        Requires SEAT role authorization.

        Note: This endpoint uses POST instead of GET to protect PII (Personally
        Identifiable Information). Email addresses should not be exposed in URL
        paths where they can appear in server logs, browser history, and proxy logs.
      parameters:
        - in: body
          name: body
          required: true
          schema:
            type: object
            required:
              - email
            properties:
              email:
                type: string
                format: email
                description: Email address to search for.
      responses:
        '200':
          description: Success
          schema:
            type: object
            properties:
              id:
                type: string
                description: The identity UUID.
          examples:
            application/json:
              {
                "id": "60e196d8-2fc9-4989-9cee-03f477c2f7cd"
              }
        '400':
          description: Bad request - invalid email format or email domain not allowed
          examples:
            application/json:
              {
                "message": "Email domain not supported for employee creation"
              }
        '403':
          description: Forbidden - user lacks SEAT role access
          examples:
            application/json:
              {
                "message": "Forbidden"
              }
        '404':
          description: Not Found - no identity exists with this email
          examples:
            application/json:
              {
                "message": "Identity not found"
              }
definitions:
  ArrayOfUsers:
    type: array
    items:
      type: object
      properties:
        user_id:
          type: string
          example: oa:123
        type:
          type: string
          example: oa
        first_name:
          type: string
          example: Alfred
        last_name:
          type: string
          example: Hitchcock
        email:
          type: string
          example: ahitchcock@theorchard.com
        account:
          type: object
          properties:
            vendor_id:
              type: string
              example: null
            subaccount_id:
              type: string
              example: null
        active:
          type: string
          enum:
            - Y
            - N
  LoginBody:
    type: object
    properties:
      request_id:
        type: string
        description: identifier for the login request.
      client_id:
        type: integer
        description: Oauth2 client id
      login:
        type: string
        description: The user's login which can be a username or an email
      password:
        type: string
        description: The user's encyrpted password
    required:
      - request_id
      - client_id
      - login
      - password
  TokenBody:
    type: object
    properties:
      client_id:
        description: the identifier of the client, e.g. 19874
        type: integer
      client_secret:
        description: the client secret
        type: string
      code:
        description: The code token
        type: string
    required:
      - client_id
      - client_secret
      - code
  user-status-put-body:
      additionalProperties: false
      properties:
        active:
          description: status of user 'Y' or 'N'.
          type: string
          enum:
            - Y
            - N
      type: object
parameters:
  client_id:
    in: query
    type: integer
    name: client_id
    description: The Oauth2 client identifier
    required: true
  client_secret:
    in: query
    type: string
    name: client_secret
    description: |
      In addition to having an identifier, each application also has a secret (string), which is passed along the different requests. It ensures the user is authorized to perform the requests, and the client is valid.
    required: true
  state:
    in: query
    type: string
    name: state
    description: |
      Applications can provide state when asking a user to be
      authenticated. This state is not used by ows-users, but is
      returned as part of the call. This allows the application to
      verify the state matches what was sent to ows-users before trying to authenticate. For more details, see the oauth2 specs. e.g. "c3cbf0a0-452d-41cd-ae9c-19273537527d"
    required: true
securityDefinitions: {}