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.

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.

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

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.

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

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:

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

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.

2020-11-26

• First release of this documentation page.