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