openapi: 3.0.3
info:
  title: Authentication Access Management Users API
  description: Authentication
  termsOfService: urn:tos
  contact: {}
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  version: '1.0'
servers:
- url: https://auth.prod.latch.com
  description: Latch Auth API base URL
tags:
- name: Users
  description: User operations
paths:
  /v1/users/{userUuid}:
    get:
      tags:
      - Users
      summary: Get User
      description: Get a single user for a DOOR partner
      operationId: getUser
      parameters:
      - name: userUuid
        in: path
        description: UUID of the user to fetch.
        required: true
        style: simple
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully retrieved user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          description: Invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      security:
      - bearerAuth: []
  /v1/users:
    get:
      tags:
      - Users
      summary: List Users
      description: Get a DOOR partner's list of users
      operationId: listUsers
      parameters:
      - name: pageSize
        in: query
        description: Max number of users to return
        required: false
        style: form
        schema:
          type: integer
          format: int32
      - name: pageToken
        in: query
        description: The token of page to return
        required: false
        style: form
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved list of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          description: Invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      security:
      - bearerAuth: []
  /v1/buildings/{buildingUuid}/residents:
    get:
      tags:
      - Users
      summary: List Building Residents
      description: Get residents based on active key memberships in a building.
      operationId: listBuildingResidents
      parameters:
      - name: buildingUuid
        in: path
        description: UUID of the building
        required: true
        style: simple
        schema:
          type: string
          format: uuid
      - name: pageSize
        in: query
        description: Max number of residents to return
        required: false
        style: form
        schema:
          type: integer
          format: int32
      - name: pageToken
        in: query
        description: The token of page to return
        required: false
        style: form
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved residents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResidentsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          description: Invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      security:
      - bearerAuth: []
components:
  schemas:
    ResidentsResponse:
      title: ResidentsResponse
      required:
      - residents
      type: object
      properties:
        nextPageToken:
          type: string
          description: Token to fetch the next page
        residents:
          type: array
          items:
            $ref: '#/components/schemas/Resident'
      description: Response from the residents endpoint. Returns first 100 residents by default
    NotFoundError:
      title: NotFoundError
      required:
      - message
      type: object
      properties:
        message:
          type: string
          enum:
          - NOT_FOUND
    InternalServerError:
      title: InternalServerError
      required:
      - message
      type: object
      properties:
        message:
          type: string
          enum:
          - INTERNAL_SERVER_ERROR
    User:
      title: User
      required:
      - email
      - firstName
      - lastName
      - userUuid
      type: object
      properties:
        accesses:
          type: array
          description: List of accesses a user has
          items:
            $ref: '#/components/schemas/UserAccess'
        email:
          type: string
          example: john.smith@example.com
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Smith
        phone:
          type: string
          example: +1-111-111-1111
        userUuid:
          type: string
          description: User identifier
          format: uuid
      description: DOOR User object
    Resident:
      title: Resident
      required:
      - email
      - firstName
      - lastName
      - userUuid
      type: object
      properties:
        email:
          type: string
          example: john.smith@example.com
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Smith
        phone:
          type: string
          example: +1-111-111-1111
        userUuid:
          type: string
          description: Unique identifier of the user
          format: uuid
      description: Resident object
    Doorcode:
      title: Doorcode
      required:
      - code
      - description
      type: object
      properties:
        code:
          type: string
          description: A 7 digit doorcode to unlock door/key
          example: '1234567'
        description:
          type: string
          description: A message to explain the doorcode result
          enum:
          - COMMUNAL_DOORCODE_CONFLICT
          - USER_HAS_GUEST_ACCESS_CONFLICT
          - USER_HAS_RESIDENT_ACCESS
          - VALID
      description: Doorcode object
    UserAccess:
      title: UserAccess
      required:
      - doorUuid
      - endTime
      - granter
      - passcodeType
      - shareable
      - startTime
      type: object
      properties:
        doorUuid:
          type: string
          description: Identifier of the Door/Key related to the access
          format: uuid
        doorcode:
          $ref: '#/components/schemas/Doorcode'
        endTime:
          type: string
          description: End time of the access
          format: date-time
        granter:
          $ref: '#/components/schemas/AccessGranter'
        passcodeType:
          type: string
          enum:
          - DAILY
          - DAILY_SINGLE_USE
          - PERMANENT
        role:
          type: string
          enum:
          - GUEST
          - NON_RESIDENT
          - RESIDENT
          - TOURER
        sdkDoorUuid:
          type: string
          description: DOOR Door/Key Unique Identifier - for SDK use only
          format: uuid
        shareable:
          type: boolean
          description: User able to share access to guests
          example: false
        startTime:
          type: string
          description: Start time of the access
          format: date-time
        userUuid:
          type: string
          description: User identifier
          format: uuid
      description: Definition of a User's Access to a Door/Key and the metadata associated
    AccessGranter:
      title: AccessGranter
      required:
      - type
      - uuid
      type: object
      properties:
        type:
          type: string
          description: Type of granter
          enum:
          - PARTNER
          - USER
        uuid:
          type: string
          description: identifier of the granter of access
          format: uuid
      description: Definition of the granter of Access
    UsersResponse:
      title: UsersResponse
      required:
      - users
      type: object
      properties:
        nextPageToken:
          type: string
          description: Token to fetch the next page
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
      description: Response from the users endpoint
    UnauthorizedError:
      title: UnauthorizedError
      required:
      - message
      type: object
      properties:
        message:
          type: string
          enum:
          - UNAUTHORIZED
    BadRequestError:
      title: BadRequestError
      required:
      - message
      type: object
      properties:
        message:
          type: string
          enum:
          - BUILDING_UUID_REQUIRED
          - EMAIL_AND_PHONE_PROVIDED
          - EMAIL_CAN_NOT_BE_EMPTY
          - EMAIL_OR_PHONE_REQUIRED
          - EMAIL_REQUIRED_FOR_PERMANENT
          - END_TIME_NOT_SUPPORTED
          - INVALID_END_TIME
          - INVALID_PHONE
          - INVALID_START_TIME
          - MISSING_END_TIME
          - PASSCODE_TYPE_CANT_BE_REVOKED
          - USER_CAN_NOT_SHARE