homeit
API docs by Redocly

homeit Auth API (2.2)

Download OpenAPI specification:

homeit Backend: backend@homeit.io Terms of Service

Introduction

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.

  • Integration Platforms can use OAuth2 to access protected resources.

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.

Overview

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"}.

Document Structure

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.

Security

HTTPS

All API requests must be made over HTTPS. Requests made over HTTP will be redirected to HTTPS.

Authentication

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:

  • API Key: Used as a query parameter. Example: https://api.homeit.io/v2/resource?apikey={{apikey}}
  • OAuth2: The OAuth2 flows produce tokens in the JSON Web Token format. This authentication method is fully compliant with the OAuth2 standard. These tokens can be used as a bearer token in the Authorization HTTP header. Example: Authorization: Bearer {{token}}

You can find additional information in the Authentication section.

Rate Limits

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:

  • 100 requests per second
  • 1000 requests per minute

Pagination

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.

Sorting

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.

Hypermedia

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.

Formatting

JSON

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.

Dates

All dates follow the ISO 8601 format standard.

Errors

In case of internal or external error, the following HTTP error codes will be returned:

  • 401 Unauthorized: Request lacks valid authentication credentials.
  • 403 Forbidden: Access to requested resource is not allowed.
  • 404 Not Found: Requested resource could not be found. Also returned if the requested route could not be found.
  • 405 Method Not Allowed: Request HTTP method is not allowed on the requested route or resource.
  • 409 Conflict: Requested data changes create conflicts with current state of resource.
  • 422 Unprocessable Entity: Payload validation failed. Usually accompanied by a detailed explanation message.
  • 429 Too Many Requests: Request rate exceeded rate limits.

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:

  • 201 Created: Successful resource creation operations.
  • 200 OK: All other successful operations.

Testing

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.

Feedback

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.

Changelog

2020-11-26

  • First release of this documentation page.

API Keys

Get all API Keys.

Get all API Keys you have access to. You may use filters to narrow your search.

Authorizations:
(oauthapikey)
query Parameters
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.

Responses

Request samples 

curl -XGET "https://auth.homeit.io/v2/apikeys?id=1&id=2&name=Example" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 2,
  • "limit": 10,
  • "skip": 0
}

Create an API Key.

Create a new API Key.

Authorizations:
(oauthapikey)
Request Body schema: application/json
required

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.

Responses

Request samples

Content type
application/json
{
  • "name": "Example",
  • "description": "Example"
}

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Get an API Key.

Get a single API Key by ID.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Responses

Request samples 

curl -XGET "https://auth.homeit.io/v2/apikeys/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Update an API Key.

Update an API Key you own.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Request Body schema: application/json
required

API Key object.

name
string

The API Key's name.

description
string

The API Key's description.

Responses

Request samples

Content type
application/json
{
  • "name": "API Key 1",
  • "description": "This is an API Key."
}

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Delete an API Key.

Delete an API Key you own.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Responses

Request samples 

curl -XDELETE "https://auth.homeit.io/v2/apikeys/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Organizations

Get all Organizations.

Get all Organizations you have access to. You may use filters to narrow your search.

Authorizations:
(oauthapikey)
query Parameters
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.

Responses

Request samples 

curl -XGET "https://auth.homeit.io/v2/organizations?id=1&id=2&name=Example" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 2,
  • "limit": 10,
  • "skip": 0
}

Get an Organization.

Get a single Organization by ID.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Responses

Request samples 

curl -XGET "https://auth.homeit.io/v2/organizations/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Update an Organization.

Update an Organization you own.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Request Body schema: application/json
required

Organization object.

name
string

The Organization's name.

description
string

The Organization's description.

Responses

Request samples

Content type
application/json
{
  • "name": "Organization 1",
  • "description": "This is an Organization."
}

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Delete an Organization.

Delete an Organization you own.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Responses

Request samples 

curl -XDELETE "https://auth.homeit.io/v2/organizations/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Users

Get all Users.

Get all Users you have access to. You may use filters to narrow your search.

Authorizations:
(oauthapikey)
query Parameters
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.

email
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.

Responses

Request samples 

curl -XGET "https://auth.homeit.io/v2/users?id=1&id=2&name=Example" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 2,
  • "limit": 10,
  • "skip": 0
}

Get a User.

Get a single User by ID.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Responses

Request samples 

curl -XGET "https://auth.homeit.io/v2/users/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Update a User.

Update a User you own.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Request Body schema: application/json
required

User object.

name
string

The User's name.

description
string

The User's description.

Responses

Request samples

Content type
application/json
{
  • "name": "User 1",
  • "description": "This is a User."
}

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Delete a User.

Delete a User you own.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Responses

Request samples 

curl -XDELETE "https://auth.homeit.io/v2/users/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Token

Generate OAuth2 tokens.

Generate new access tokens or refresh existing tokens. This route is only used by OAuth clients.

Authorizations:
oauth

Request samples 

curl -XGET "https://auth.homeit.io/v2/oauth/token"
  -H "Content-type: application/json"
  -H "Authorization: Basic {{token}}"

API Key

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": [
    ],
  • "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
}

Organization

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": {
    },
  • "location": {
    },
  • "timezone": "Europe/Lisbon",
  • "email": {
    },
  • "phone": {
    },
  • "isActive": true,
  • "dateCreated": "2021-01-01T00:00:00.000Z",
  • "dateUpdated": "2021-01-01T00:00:00.000Z",
  • "deleted": false
}

User

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": {
    },
  • "phone": {
    },
  • "organization": 123456,
  • "organizationRole": "admin",
  • "scopes": [
    ],
  • "about": "This is a User.",
  • "isActive": true,
  • "dateCreated": "2021-01-01T00:00:00.000Z",
  • "dateUpdated": "2021-01-01T00:00:00.000Z",
  • "deleted": false
}