REST API
========

Examples
--------

You can see examples and test this API here: `Swagger UI </swaggerui/>`_

Authentication
--------------

To test endpoints that need authentication generate an auth token calling ``/login``. Then click the button on the received email to validate this token.

After that pass the token as  Authorization header:

``Authorization: TOKEN your-token-here``

Errors
------

When API call returns an error you will get a response like this:

.. code-block:: json

    {
        "error": {
            "code": 1,
            "message": "Error description"
        }
    }  

When a call is successful you will get something like this:

.. code-block:: json

    {
        "result": {
           "someContent": "someValue"
        }
    }

List or possible error codes:

* **-1**:  requesting action that needs authentication
* **-32602**:  invalid params
* **0**: general error
* **1**: the auth token has not been validated via email
* **2**: don't have permissions to access a resource
* **3**: something was not found
* **4**: cannot insert something because it already exists
* **5**: integrity checks for firmware failed
* **6**: when enabling a firmware update for a lock with version <= than current
* **7**: when enabling a beta firmware for a lock that doesn't allow betas
* **8**: when integrity checks for an egg failed
* **9**: when user tries to delete email that is set as contact email
* **10**: when trying to add a time restriction with hour range where end <= start
* **11**: when adding a time restriction with a weekday <0 or >6
* **12**: when adding a time restriction with a monthday <1 or >31
* **13**: when adding a time restriction with a month <0 or >11
* **14**: when trying to create more key copies than allowed
* **15**: when trying to set max_copies to a negative number
* **16**: when user already has a key for that lock
* **17**: when trying to create ACL and its max_copies + brothers.max_copies > father.max_copies
* **18**: when creating an ACL with a permission that the parent doesn't have
* **19**: when ACL validity period falls completely outside of parent ACL validity period
* **20**: when an email is already used by another user
* **21**: when trying to pass lock ownership to a non-existing user
* **22**: when trying to pass a wrong day to logs search
* **23**: when trying to do something with a non-existing user
* **24**: when trying to do something with a non-existing group
* **25**: when trying to create an ACL passing both email & group id
* **26**: when trying to create/modify a group with field max_members <= 0
* **27**: when trying to add a group member exceeds max_members
* **28**: when trying to use as replacement a lock that has more than 1 key or has 1 but it's not the owner one
* **29**: when trying to do some action with an actuator that doesn't exist
* **30**: when receiving string with XSS characters
* **31**: when trying to delete an account while owning a lock
* **32**: when trying to login with a non-existing email
* **33**: when failed sending login email
* **34**: when date range start if greater than end
* **35**: when passing an invalid timezone
* **36**: when creating a key exceeds hardware's max_keys
* **37**: when trying to assign keys to hardware but manufacturer doesn't have enough available keys


API Reference
-------------

.. openapi:: ../static/admin.nearkey.io/swagger/swagger.yaml
    :group: