openapi: 3.0.3
info:
  title: Authentication Access Management 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: Access Management
  description: User access management operations
paths:
  /v1/users:
    post:
      tags:
      - Access Management
      summary: Grant Access to User
      description: Create DOOR user and grant access to doors/keys
      operationId: grantAccessToUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostUserRequest'
      responses:
        '200':
          description: Successfully created user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostUserResponse'
        '201':
          description: Created
        '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: []
  /v2/users:
    post:
      tags:
      - Access Management
      summary: Grant Access to User V2
      description: Create DOOR user and grant access to doors/keys. Returns a richer response than V1.
      operationId: grantAccessToUserV2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostUserRequest'
      responses:
        '200':
          description: Successfully created user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '201':
          description: Created
        '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/{keyUuid}/accesses:
    get:
      tags:
      - Access Management
      summary: List Accesses By Key
      description: Get all accesses on a key for a DOOR partner
      operationId: listKeyAccesses
      parameters:
      - name: keyUuid
        in: path
        description: UUID of the key to get accesses for.
        required: true
        style: simple
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully retrieved key accesses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyAccessesResponse'
        '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/users/{userUuid}/doors/{doorUuid}:
    delete:
      tags:
      - Access Management
      summary: Revoke User Access
      description: Revoke user access to the given door/key.
      operationId: revokeUserAccess
      parameters:
      - name: userUuid
        in: path
        description: UUID of the user that we want to revoke access to.
        required: true
        style: simple
        schema:
          type: string
          format: uuid
      - name: doorUuid
        in: path
        description: UUID of door/key we want to revoke access to.
        required: true
        style: simple
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully revoked access to the given door/key.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
        '204':
          description: No Content
        '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: []
    patch:
      tags:
      - Access Management
      summary: Update User Access
      description: Update user access to the given door/key.
      operationId: updateUserAccess
      parameters:
      - name: userUuid
        in: path
        description: UUID of the user that we want to update access for.
        required: true
        style: simple
        schema:
          type: string
          format: uuid
      - name: doorUuid
        in: path
        description: UUID of door/key we want to update access for.
        required: true
        style: simple
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserDoorRequest'
      responses:
        '200':
          description: Successfully updated access to the given door/key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '204':
          description: No Content
        '400':
          description: Bad Request Error
          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: []
components:
  schemas:
    KeyAccess:
      title: KeyAccess
      required:
      - doors
      - granter
      - keyUuid
      - passcodeType
      - shareable
      - startTime
      - userUuid
      type: object
      properties:
        doors:
          type: array
          description: Per-door/key access data
          items:
            $ref: '#/components/schemas/KeyAccessDoor'
        endTime:
          type: string
          description: End time of the access
          format: date-time
        granter:
          $ref: '#/components/schemas/AccessGranter'
        keyUuid:
          type: string
          description: Key unique identifier
          format: uuid
        passcodeType:
          type: string
          enum:
          - DAILY
          - DAILY_SINGLE_USE
          - PERMANENT
        role:
          type: string
          enum:
          - GUEST
          - NON_RESIDENT
          - RESIDENT
          - TOURER
        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: A user's access to a key, with per-door/key data grouped in the doors/keys list
    KeyAccessesResponse:
      title: KeyAccessesResponse
      required:
      - accesses
      type: object
      properties:
        accesses:
          type: array
          items:
            $ref: '#/components/schemas/KeyAccess'
      description: Response from the key accesses endpoint
    PostUserResponse:
      title: PostUserResponse
      required:
      - doors
      - userUuid
      type: object
      properties:
        doors:
          type: array
          description: List of doors/keys user has access to
          items:
            $ref: '#/components/schemas/Door'
        userUuid:
          type: string
          description: User unique identifier
          format: uuid
      description: Response from the post users endpoint
    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
    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.
    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
    KeyAccessDoor:
      title: KeyAccessDoor
      required:
      - sdkDoorUuid
      type: object
      properties:
        doorcode:
          $ref: '#/components/schemas/Doorcode'
        sdkDoorUuid:
          type: string
          description: DOOR Door/Key Unique Identifier
          format: uuid
      description: Door/Key-specific data within a key access
    UpdateUserDoorRequest:
      title: UpdateUserDoorRequest
      type: object
      properties:
        endTime:
          type: string
          description: End time of access to door/key
          format: date-time
        role:
          type: string
          enum:
          - GUEST
          - NON_RESIDENT
          - RESIDENT
          - TOURER
        shareable:
          type: boolean
          description: User able to share access to guests
          example: false
      description: JSON representation of the user's access to the door/key to update for the patch users door/key endpoint
    PostUserRequest:
      title: PostUserRequest
      required:
      - firstName
      - lastName
      - passcodeType
      - shareable
      - startTime
      type: object
      properties:
        doorUuids:
          type: array
          items:
            type: string
            format: uuid
        keyUuids:
          type: array
          items:
            type: string
            format: uuid
        email:
          type: string
          description: Email of user
        endTime:
          type: string
          description: End time of access to doors/keys
          format: date-time
        firstName:
          maxLength: 2147483647
          minLength: 1
          type: string
          description: First name of user
        lastName:
          maxLength: 2147483647
          minLength: 1
          type: string
          description: Last name of user
        passcodeType:
          type: string
          enum:
          - DAILY
          - DAILY_SINGLE_USE
          - PERMANENT
        phone:
          type: string
          description: Phone number of user
        role:
          type: string
          enum:
          - GUEST
          - NON_RESIDENT
          - RESIDENT
          - TOURER
        shareable:
          type: boolean
          description: User able to share access to guests
          example: false
        shouldNotify:
          type: boolean
          description: Toggle user invite notification
          example: false
        startTime:
          type: string
          description: Start time of access to doors/keys
          format: date-time
      description: JSON representation of the user for the post users endpoint
    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
    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