openapi: 3.0.3
info:
  title: Authentication Access Management Doors and Keys 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: Doors and Keys
  description: Door/Key and key operations
paths:
  /v1/doors:
    get:
      tags:
      - Doors and Keys
      summary: List Doors
      description: Get a DOOR partner's list of doors/keys
      operationId: listDoors
      parameters:
      - name: pageSize
        in: query
        description: Max number of doors/keys 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
      - name: buildingUuid
        in: query
        description: Building UUID for filtering doors/keys
        required: false
        style: form
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully retrieved list of doors/keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DoorsResponse'
        '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/keys:
    get:
      tags:
      - Doors and Keys
      summary: List Keys
      description: Get a DOOR partner's list of keys for a building
      operationId: listKeys
      parameters:
      - name: pageSize
        in: query
        description: Max number of keys 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
      - name: buildingUuid
        in: query
        description: Building UUID for filtering keys
        required: false
        style: form
        schema:
          type: string
          format: uuid
      - name: includeDoors
        in: query
        description: When true, each key in the response includes the list of doors/keys it grants access to. Defaults to false.
        required: false
        style: form
        schema:
          type: boolean
      responses:
        '200':
          description: Successfully retrieved list of keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeysResponse'
        '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:
    KeysResponse:
      title: KeysResponse
      required:
      - keys
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/Key'
        nextPageToken:
          type: string
          description: Token to fetch the next page
          example: '1'
      description: Response from the keys endpoint
    DoorsResponse:
      title: DoorsResponse
      required:
      - doors
      type: object
      properties:
        doors:
          type: array
          items:
            $ref: '#/components/schemas/Door'
        nextPageToken:
          type: string
          description: Token to fetch the next page
          example: '1'
      description: Response from the doors/keys endpoint
    Key:
      title: Key
      required:
      - name
      - uuid
      type: object
      properties:
        accountUuid:
          type: string
          description: UUID of the account that owns the key
          format: uuid
        buildingUuid:
          type: string
          description: UUID of the building
          format: uuid
        doors:
          type: array
          description: List of doors/keys the key grants access to. Only populated when listKeys is called with includeDoors=true.
          items:
            $ref: '#/components/schemas/KeyDoor'
        doorsType:
          type: string
          description: Type of doors/keys the key grants access to.
          enum:
          - DOOR
          - ELEVATOR
        endTime:
          type: string
          description: End time of key access
          format: date-time
        keyType:
          type: string
          description: 'Distinguishes single-door/key Keys from regular multi-door/key Keys created in DOOR OS. - `SINGLE`: single-door/key Key. - `REGULAR`: regular DOOR OS Key. '
          enum:
          - REGULAR
          - SINGLE
        name:
          type: string
          description: Name of the key
        startTime:
          type: string
          description: Start time of key access
          format: date-time
        uuid:
          type: string
          description: Key unique identifier
          format: uuid
      description: DOOR Key object
    InternalServerError:
      title: InternalServerError
      required:
      - message
      type: object
      properties:
        message:
          type: string
          enum:
          - INTERNAL_SERVER_ERROR
    Battery:
      title: Battery
      required:
      - lastUpdated
      - percentage
      type: object
      properties:
        lastUpdated:
          type: integer
          description: Indicates latest time when the battery percentage was updated
          format: int64
          example: 1737137633
        percentage:
          type: integer
          description: Estimated battery percentage
          format: int32
          example: 92
      description: Information on the device battery.
    KeyDoor:
      title: KeyDoor
      required:
      - name
      - sdkDoorUuid
      type: object
      properties:
        name:
          type: string
          description: Name of the door/key
        sdkDoorUuid:
          type: string
          description: DOOR Door/Key Unique Identifier - for SDK use only
          format: uuid
        type:
          type: string
          description: Door/Key type.
          enum:
          - COMMUNAL
          - ELEVATOR
          - ENTRANCE
          - RESIDENCE
          - SERVICE
      description: Door/Key associated with a Key
    DeviceInfo:
      title: DeviceInfo
      required:
      - battery
      - serialNumber
      - type
      type: object
      properties:
        battery:
          $ref: '#/components/schemas/Battery'
        serialNumber:
          type: string
          description: Serial number of the lock device
          example: 0123456789
        type:
          type: string
          description: DOOR device type
          example: C
      description: Additional information about the physical lock device.
    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
    Door:
      title: Door
      required:
      - buildingUuid
      - name
      - type
      - uuid
      type: object
      properties:
        accessibilityType:
          type: string
          enum:
          - COMMUNAL
          - PRIVATE
        buildingUuid:
          type: string
          description: UUID of the building
          format: uuid
        device:
          $ref: '#/components/schemas/DeviceInfo'
        isConnected:
          type: boolean
          description: Indicates whether a door/key is connected to the internet via wifi/ethernet/hub
          example: false
        name:
          type: string
          description: Name of the door/key
        sdkDoorUuid:
          type: string
          description: DOOR Door/Key Unique Identifier - for SDK use only
          format: uuid
        type:
          type: string
          description: Type of door/key
          enum:
          - DOOR
          - ELEVATOR
        uuid:
          type: string
          description: Door/Key unique identifier
          format: uuid
      description: DOOR Door/Key object