OpenAPI Specification
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