Download OpenAPI specification:
homeit is a property management system, designed for short-term rentals. The homeit platform allows you to manage all your properties from a single place.
The homeit Auth API allows you to manage your user settings, organization, and API keys, and login via OAuth2.
If you have any suggestions or questions regarding this API, please send us an email.
These documentation pages were automatically generated from an OpenAPI file, and are intended to be used by developers as detailed descriptions of our API.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals, as shown here.
What this API does for partners
The homeit Auth API allows partners to integrate with the homeit network.
Our API is REST-compliant and uses resource-oriented URLs and common HTTP response codes to indicate API errors.
This document is entirely written in English. Similarly, all enumerated values used in this API are also written in English.
The API is available at https://auth.homeit.io/v2
.
This API consists of several resource routes. Each resource route allows a user to find, create, update or remove a specific resource type.
All resource routes follow the same structure and offer similar high-level functionality. When applicable, resource routes include the following endpoints:
GET /{{resource}}
: Find all available resources the authenticated user is allowed to access. Search query parameters may be used to filter results.POST /{{resource}}
: Create a new resource.GET /{{resource}}/{{id}}
: Create a specific resource by its ID.PUT /{{resource}}/{{id}}
: Update a specific resource.DELETE /{{resource}}/{{id}}
: Remove a specific resource.For example, to update the name of a User resource with ID 123456
to "HOMEIT", an HTTP PUT request should be sent to https://auth.homeit.io/v2/users/123456
with the body {"name":"HOMEIT"}
.
This document's first sections provide details on how to use the API, including security considerations, data formats, and testing instructions.
Then, all resource routes are listed. In this section, you will find request and response formats for each resource type, as well as example responses and code snippets.
Finally, we include the data model for each resource type, along with data type requirements and example values. Fields present in a resource document but not included in the resource's data model should not be used, as they are subject to change at any moment without prior notice. Deprecated fields will be marked as such and should also not be used.
Most API routes require authentication using an API Key or a Bearer token. Requests made without authentication will fail with a 401 Unauthorized
error.
When applicable, requests may be authenticated using one of the following methods:
https://api.homeit.io/v2/resource?apikey={{apikey}}
Authorization
HTTP header. Example: Authorization: Bearer {{token}}
You can find additional information in the Authentication section.
If too many requests are sent in a short amount of time, a 429 Too Many Requests
error is returned until request rates return to normal. Client applications should honour the following request rate limits:
All operations are automatically paginated in the following way:
{ docs: [], total: 120, limit: 10, skip: 0 }
Operations which return a single resource are still paginated, but will show total
and limit
values of 1.
You can define a limit
on the number of documents to be returned which can range between 1 and 100 items. The default is 10 items.
Similarly, you can skip
any number of documents, effectively setting the starting position by providing an index. This index should not exceed the total
amount of available documents.
For example, https://auth.homeit.io/v2/users?limit=100&skip=10
returns at most 100 items, skipping the first 10 documents.
All list operations can be sorted by any of the document's fields, as long as its assigned value is a number, a string or a date.
The sortBy
parameter provides the key you want to sort by, while the order
parameter tells the API in which order you want your results: asc
for ascending and desc
for descending.
For example, https://auth.homeit.io/v2/users?sortBy=id&order=desc
returns items sorted by ID, in descending order.
All operations return a collection of hypermedia links to other pages of the same request or other related requests. This collection follows the HAL format.
This behavior can be disabled by setting the hypermedia
query parameter to false
.
For example, https://auth.homeit.io/v2/users?hypermedia=false
returns a response without hypermedia information.
All API responses are given in JSON format. All requests bodies should also be provided as JSON.
Request body content type should be application/json
. Response body content type will always be application/json+hal
.
All dates follow the ISO 8601 format standard.
In case of internal or external error, the following HTTP error codes will be returned:
Other 4XX and 5XX error codes may be returned upon malformed request payload or gateway errors.
During normal operation, the following HTTP codes will be returned:
All operations accept a dry
boolean query parameter. When testing, you can enable dry-run mode by setting this parameter to true
.
In this mode, all side-effects (such as database writes) are disabled, but responses are still returned as normal.
For example, an update request to https://auth.homeit.io/v2/users/123?dry=true
would return the updated document, but no changes would be persisted.
If you would like to report an error or have any suggestions or questions regarding this API, please send us an email to backend@homeit.io. Any feedback is greatly appreciated. Please, use English for all communications.
Get all API Keys you have access to. You may use filters to narrow your search.
id | Array of integers <int64> [ items <int64 > ] Example: id=123 A list of resource IDs. |
name | string Example: name=Example The resource's name, or part of it. Case-insensitive. |
description | string Example: description=Example The resource's description, or part of it. Case-insensitive. |
isActive | boolean Example: isActive=true Filter by active status. |
createdBefore | string Example: createdBefore=2020-01-01T00:00:00.000Z Filter by creation date. Format MUST comply with ISO 8601. |
createdAfter | string Example: createdAfter=2020-01-01T00:00:00.000Z Filter by creation date. Format MUST comply with ISO 8601. |
dry | boolean Default: false Example: dry=true Enable dry-run mode, for testing. |
hypermedia | boolean Default: true Example: hypermedia=false Disable hypermedia links in response. |
curl -XGET "https://auth.homeit.io/v2/apikeys?id=1&id=2&name=Example" \ -H "Content-type: application/json" \ -H "Authorization: Bearer {{token}}"
{- "docs": [
- {
- "id": 123,
- "name": "API Key 1",
- "description": "This is an API Key.",
- "mac": "8426ab951c73",
- "serialNumber": "SERIAL123",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}, - {
- "id": 321,
- "name": "API Key 2",
- "description": "This is an API Key.",
- "mac": "8426ab951c74",
- "serialNumber": "SERIAL321",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}
], - "total": 2,
- "limit": 10,
- "skip": 0
}
Create a new API Key.
API Key object.
name | string The API Key's name. |
description | string The API Key's description. |
scope | Array of strings unique Items Value: "external" A list of authorization scopes. |
{- "name": "Example",
- "description": "Example"
}
{- "docs": [
- {
- "id": 123,
- "name": "API Key 1",
- "description": "This is an API Key.",
- "mac": "8426ab951c73",
- "serialNumber": "SERIAL123",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}
], - "total": 1,
- "limit": 1,
- "skip": 0
}
Get a single API Key by ID.
id | integer <int64> Example: 123 A resource's ID. |
curl -XGET "https://auth.homeit.io/v2/apikeys/1" \ -H "Content-type: application/json" \ -H "Authorization: Bearer {{token}}"
{- "docs": [
- {
- "id": 123,
- "name": "API Key 1",
- "description": "This is an API Key.",
- "mac": "8426ab951c73",
- "serialNumber": "SERIAL123",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}
], - "total": 1,
- "limit": 1,
- "skip": 0
}
Update an API Key you own.
id | integer <int64> Example: 123 A resource's ID. |
API Key object.
name | string The API Key's name. |
description | string The API Key's description. |
{- "name": "API Key 1",
- "description": "This is an API Key."
}
{- "docs": [
- {
- "id": 123,
- "name": "API Key 1",
- "description": "This is an API Key.",
- "mac": "8426ab951c73",
- "serialNumber": "SERIAL123",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}
], - "total": 1,
- "limit": 1,
- "skip": 0
}
Delete an API Key you own.
id | integer <int64> Example: 123 A resource's ID. |
curl -XDELETE "https://auth.homeit.io/v2/apikeys/1" \ -H "Content-type: application/json" \ -H "Authorization: Bearer {{token}}"
{- "docs": [
- {
- "id": 123,
- "name": "API Key 1",
- "description": "This is an API Key.",
- "mac": "8426ab951c73",
- "serialNumber": "SERIAL123",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": true,
- "deletedAt": "2021-01-01T00:00:00.000Z"
}
], - "total": 1,
- "limit": 1,
- "skip": 0
}
Get all Organizations you have access to. You may use filters to narrow your search.
id | Array of integers <int64> [ items <int64 > ] Example: id=123 A list of resource IDs. |
name | string Example: name=Example The resource's name, or part of it. Case-insensitive. |
description | string Example: description=Example The resource's description, or part of it. Case-insensitive. |
isActive | boolean Example: isActive=true Filter by active status. |
createdBefore | string Example: createdBefore=2020-01-01T00:00:00.000Z Filter by creation date. Format MUST comply with ISO 8601. |
createdAfter | string Example: createdAfter=2020-01-01T00:00:00.000Z Filter by creation date. Format MUST comply with ISO 8601. |
dry | boolean Default: false Example: dry=true Enable dry-run mode, for testing. |
hypermedia | boolean Default: true Example: hypermedia=false Disable hypermedia links in response. |
curl -XGET "https://auth.homeit.io/v2/organizations?id=1&id=2&name=Example" \ -H "Content-type: application/json" \ -H "Authorization: Bearer {{token}}"
{- "docs": [
- {
- "id": 123,
- "name": "Organization 1",
- "description": "This is an Organization.",
- "mac": "8426ab951c73",
- "serialNumber": "SERIAL123",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}, - {
- "id": 321,
- "name": "Organization 2",
- "description": "This is an Organization.",
- "mac": "8426ab951c74",
- "serialNumber": "SERIAL321",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}
], - "total": 2,
- "limit": 10,
- "skip": 0
}
Get a single Organization by ID.
id | integer <int64> Example: 123 A resource's ID. |
curl -XGET "https://auth.homeit.io/v2/organizations/1" \ -H "Content-type: application/json" \ -H "Authorization: Bearer {{token}}"
{- "docs": [
- {
- "id": 123,
- "name": "Organization 1",
- "description": "This is an Organization.",
- "mac": "8426ab951c73",
- "serialNumber": "SERIAL123",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}
], - "total": 1,
- "limit": 1,
- "skip": 0
}
Update an Organization you own.
id | integer <int64> Example: 123 A resource's ID. |
Organization object.
name | string The Organization's name. |
description | string The Organization's description. |
{- "name": "Organization 1",
- "description": "This is an Organization."
}
{- "docs": [
- {
- "id": 123,
- "name": "Organization 1",
- "description": "This is an Organization.",
- "mac": "8426ab951c73",
- "serialNumber": "SERIAL123",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}
], - "total": 1,
- "limit": 1,
- "skip": 0
}
Delete an Organization you own.
id | integer <int64> Example: 123 A resource's ID. |
curl -XDELETE "https://auth.homeit.io/v2/organizations/1" \ -H "Content-type: application/json" \ -H "Authorization: Bearer {{token}}"
{- "docs": [
- {
- "id": 123,
- "name": "Organization 1",
- "description": "This is an Organization.",
- "mac": "8426ab951c73",
- "serialNumber": "SERIAL123",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": true,
- "deletedAt": "2021-01-01T00:00:00.000Z"
}
], - "total": 1,
- "limit": 1,
- "skip": 0
}
Get all Users you have access to. You may use filters to narrow your search.
id | Array of integers <int64> [ items <int64 > ] Example: id=123 A list of resource IDs. |
name | string Example: name=Example The resource's name, or part of it. Case-insensitive. |
Array of strings Example: email=example@example.com An email address, or part of it. Case-insensitive. | |
isActive | boolean Example: isActive=true Filter by active status. |
createdBefore | string Example: createdBefore=2020-01-01T00:00:00.000Z Filter by creation date. Format MUST comply with ISO 8601. |
createdAfter | string Example: createdAfter=2020-01-01T00:00:00.000Z Filter by creation date. Format MUST comply with ISO 8601. |
dry | boolean Default: false Example: dry=true Enable dry-run mode, for testing. |
hypermedia | boolean Default: true Example: hypermedia=false Disable hypermedia links in response. |
curl -XGET "https://auth.homeit.io/v2/users?id=1&id=2&name=Example" \ -H "Content-type: application/json" \ -H "Authorization: Bearer {{token}}"
{- "docs": [
- {
- "id": 123,
- "name": "User 1",
- "description": "This is a User.",
- "mac": "8426ab951c73",
- "serialNumber": "SERIAL123",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}, - {
- "id": 321,
- "name": "User 2",
- "description": "This is a User.",
- "mac": "8426ab951c74",
- "serialNumber": "SERIAL321",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}
], - "total": 2,
- "limit": 10,
- "skip": 0
}
Get a single User by ID.
id | integer <int64> Example: 123 A resource's ID. |
curl -XGET "https://auth.homeit.io/v2/users/1" \ -H "Content-type: application/json" \ -H "Authorization: Bearer {{token}}"
{- "docs": [
- {
- "id": 123,
- "name": "User 1",
- "description": "This is a User.",
- "mac": "8426ab951c73",
- "serialNumber": "SERIAL123",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}
], - "total": 1,
- "limit": 1,
- "skip": 0
}
Update a User you own.
id | integer <int64> Example: 123 A resource's ID. |
User object.
name | string The User's name. |
description | string The User's description. |
{- "name": "User 1",
- "description": "This is a User."
}
{- "docs": [
- {
- "id": 123,
- "name": "User 1",
- "description": "This is a User.",
- "mac": "8426ab951c73",
- "serialNumber": "SERIAL123",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}
], - "total": 1,
- "limit": 1,
- "skip": 0
}
Delete a User you own.
id | integer <int64> Example: 123 A resource's ID. |
curl -XDELETE "https://auth.homeit.io/v2/users/1" \ -H "Content-type: application/json" \ -H "Authorization: Bearer {{token}}"
{- "docs": [
- {
- "id": 123,
- "name": "User 1",
- "description": "This is a User.",
- "mac": "8426ab951c73",
- "serialNumber": "SERIAL123",
- "isOnline": true,
- "versionHw": "1.0.0",
- "versionFw": "1.0.0",
- "versionFwFactory": "1.0.0",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": true,
- "deletedAt": "2021-01-01T00:00:00.000Z"
}
], - "total": 1,
- "limit": 1,
- "skip": 0
}
id | integer <int64> The API Key's numeric ID. |
name | string The API Key's name. |
description | string The API Key's description. |
token | string The API Key's token. |
isActive | boolean (isActive) Is the resource active? |
dateCreated | string (dateCreated) Creation date and time. Format MUST comply with ISO 8601. |
dateUpdated | string (dateUpdated) Last update date and time. Format MUST comply with ISO 8601. |
deleted | boolean (deleted) Is the resource deleted? |
deletedAt | string (deletedAt) Deletion date and time. Format MUST comply with ISO 8601. |
API Key Example
{- "id": 123,
- "name": "API Key 1",
- "description": "This is an API Key.",
- "user": 123456,
- "token": "TOKEN123",
- "scope": [
- "external"
], - "expires": "2030-01-01T00:00:00.000Z",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}
id | integer <int64> The Organization's numeric ID. |
name | string The Organization's name. |
description | string The Organization's description. |
mac | string The Organization's MAC Address. |
serialNumber | string The Organization's serial number. |
isOnline | boolean Is the Organization online? |
versionHw | string The Organization's hardware version. Follows SemVer. |
versionFw | string The Organization's firmware Version. Follows SemVer. |
versionFwFactory | string The Organization's factory firmware version. Follows SemVer. |
isActive | boolean (isActive) Is the resource active? |
dateCreated | string (dateCreated) Creation date and time. Format MUST comply with ISO 8601. |
dateUpdated | string (dateUpdated) Last update date and time. Format MUST comply with ISO 8601. |
deleted | boolean (deleted) Is the resource deleted? |
deletedAt | string (deletedAt) Deletion date and time. Format MUST comply with ISO 8601. |
Organization Example
{- "id": 123,
- "name": "Organization 1",
- "description": "This is an Organization.",
- "vatin": "999999999",
- "address": {
- "formatted": "Rua Augusta 2, Lisboa, Portugal",
- "apartmentNumber": "Esq",
- "floor": 1,
- "streetNumber": 1,
- "street": "Rua Augusta",
- "locality": "Lisboa",
- "area": "Baixa",
- "postalCode": 1000,
- "country": "Portugal"
}, - "location": {
- "type": "Point",
- "coordinates": [
- 38.730631,
- -9.154699
]
}, - "timezone": "Europe/Lisbon",
- "email": {
- "address": "example@example.com"
}, - "phone": {
- "number": "+351912345678"
}, - "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}
id | integer <int64> The User's numeric ID. |
name | string The User's name. |
description | string The User's description. |
mac | string The User's MAC Address. |
serialNumber | string The User's serial number. |
isOnline | boolean Is the User online? |
versionHw | string The User's hardware version. Follows SemVer. |
versionFw | string The User's firmware Version. Follows SemVer. |
versionFwFactory | string The User's factory firmware version. Follows SemVer. |
isActive | boolean (isActive) Is the resource active? |
dateCreated | string (dateCreated) Creation date and time. Format MUST comply with ISO 8601. |
dateUpdated | string (dateUpdated) Last update date and time. Format MUST comply with ISO 8601. |
deleted | boolean (deleted) Is the resource deleted? |
deletedAt | string (deletedAt) Deletion date and time. Format MUST comply with ISO 8601. |
User Example
{- "id": 123,
- "name": "User 1",
- "email": {
- "address": "example@example.com"
}, - "phone": {
- "number": "+351912345678"
}, - "organization": 123456,
- "organizationRole": "admin",
- "scopes": [
- "host",
- "external"
], - "about": "This is a User.",
- "isActive": true,
- "dateCreated": "2021-01-01T00:00:00.000Z",
- "dateUpdated": "2021-01-01T00:00:00.000Z",
- "deleted": false
}