openapi: 3.0.1
info:
  title: Users API
  description: Provides access to Hyperpoof user information.
  version: '1.0'
servers:
  - url: https://api.hyperproof.app/v1/users
    description: Hyperproof US
  - url: https://api.hyperproofgov.app/v1/users
    description: Hyperproof Gov
  - url: https://api.hyperproof.eu/v1/users
    description: Hyperproof EU
security:
  - oauth2: []
paths:
  /me:
    get:
      summary: Get User
      description: >
        `GET /users/me`


        #### Description


        Retrieves the stored profile information for the requesting user,
        including details such as name, email, and organization membership.
      operationId: get-user
      parameters:
        - name: expand
          in: query
          description: >-
            Comma separated list of fields to expand.  Supported values:
            identityProviders, organizations.
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                givenName: John
                surname: Smith
                email: john.smith@example.com
                language: en
                locale: US
                timeZone: America/Los_Angeles
                identityProviders:
                  - google.com
                  - okta.com
                organizationRoleId: b97cf308-2504-4b56-bece-1f523070e2d9
                lastLogin: '2023-05-12T14:16:27.4176600+00:00'
                state: verified
                verifiedOn: '2023-05-12T14:16:27.4176600+00:00'
                termsAcceptedOn: '2023-05-12T14:16:27.4176600+00:00'
  /:
    get:
      summary: Get Users
      description: >
        `GET /`


        #### Description


        Retrieves a list of all users in an organization, including their names,
        roles, and status information.
      operationId: get-org-users
      parameters:
        - name: expand
          in: query
          description: >-
            Comma separated list of fields to expand.  Supported values:
            identityProviders, organizationRoleId.
          schema:
            type: string
        - name: includeDeactivated
          in: query
          description: Whether or not to include deactivated users in the response.
          schema:
            type: boolean
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationUserCollection'
              example:
                - id: 82182460-f0cf-11ed-9f4f-0e9de14f3c22
                  givenName: John
                  surname: Smith
                  email: john.smith@example.com
                  language: en
                  locale: US
                  timeZone: America/Los_Angeles
                  userId: 8217610f-f0cf-11ed-9f4f-0e9de14f3c22
                  type: activeUser
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            user.read: Grants read access to users
  schemas:
    ExternalUserLink:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the external user link.
        orgId:
          type: string
          format: uuid
          description: The unique identifier of the organization the link belongs to.
        userId:
          type: string
          format: uuid
          description: The unique identifier of the user the link belongs to.
        orgUserId:
          type: string
          format: uuid
          description: The unique identifier of the organization user the link belongs to.
        source:
          type: string
          description: The name of the external source.
        externalUserId:
          type: string
          description: The unique identifier of the external user in the external source.
        userUpdatedOn:
          type: string
          format: date-time
          description: The date and time the user link was last updated (ISO-8601 format).
        givenName:
          type: string
          description: The given name of the external user.
        surname:
          type: string
          description: The surname of the external user.
    OrganizationUserCollection:
      type: array
      description: A list of organization users
      items:
        $ref: '#/components/schemas/OrganizationUser'
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the user.
        email:
          type: string
          description: The email address of the user.
        givenName:
          type: string
          description: The given name of the user.
        surname:
          type: string
          description: The surname of the user.
        language:
          type: string
          description: The language preference of the user.
        locale:
          type: string
          description: The locale preference of the user.
        timeZone:
          type: string
          description: The time zone preference of the user.
        identityProviders:
          type: array
          description: The list of identity providers for the user.
          items:
            type: string
        organizationRoleId:
          type: string
          format: uuid
          description: The organization role identifier for the user.
        lastLogin:
          type: string
          format: date-time
          description: The date and time of the user's last login (ISO-8601 format).
        state:
          type: string
          description: The state of the user.
          enum:
            - pending
            - valid
            - not_invited
            - disabled
            - erased
        verifiedOn:
          type: string
          format: date-time
          description: The date the user was verified (ISO-8601 format).
        termsAcceptedOn:
          type: string
          format: date-time
          description: The date the terms were accepted (ISO-8601 format).
      example:
        id: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        givenName: John
        surname: Smith
        email: john.smith@example.com
        language: en
        locale: US
        timeZone: America/Los_Angeles
        identityProviders:
          - google.com
          - okta.com
        organizationRoleId: b97cf308-2504-4b56-bece-1f523070e2d9
        lastLogin: '2023-05-12T14:16:27.41766Z'
        state: verified
        verifiedOn: '2023-05-12T14:16:27.41766Z'
        termsAcceptedOn: '2023-05-12T14:16:27.41766Z'
    OrganizationUser:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the organization user.
        status:
          type: string
          description: The status of the organization user.
          enum:
            - active
            - archived
            - deleted
            - pending
            - canceled
        email:
          type: string
          description: The email address of the organization user.
        givenName:
          type: string
          description: The given name of the organization user.
        surname:
          type: string
          description: The surname of the organization user.
        language:
          type: string
          description: The language preference of the organization user.
        locale:
          type: string
          description: The locale preference of the organization user.
        timeZone:
          type: string
          description: The time zone preference of the organization user.
        userId:
          type: string
          format: uuid
          description: The user identifier of the organization user.
        type:
          type: string
          description: The type of organization user.
          enum:
            - activeUser
            - contact
            - deactivatedUser
            - serviceAccount
            - deactivatedServiceAccount
            - syncServiceAccount
            - deactivatedSyncServiceAccount
        externalUserLinks:
          type: array
          description: ''
          items:
            $ref: '#/components/schemas/ExternalUserLink'
      example:
        id: 82182460-f0cf-11ed-9f4f-0e9de14f3c22
        givenName: John
        surname: Smith
        email: john.smith@example.com
        language: en
        locale: US
        timeZone: America/Los_Angeles
        userId: 8217610f-f0cf-11ed-9f4f-0e9de14f3c22
        type: activeUser
