Quickstart
==========

Create API token
----------------

User must be the owner of the lock or been added as admin of it.


.. code-block:: shell
    
    curl -X POST -d '{"email":"admin@example.com", "device_id":"api-token123", "device_desc":"API key for integration 1" }' https://api.nearkey.io/login

.. note::
    You can put anything on ``"device_desc"`` but make sure ``"device_id"`` starts with ``api-``

Will return a JSON with the API token:

.. code-block:: json

    {
        "result": {
            "token": "xxxxxxxxxxxxxxxxxx"
        }
    }

Now you must press the button on the received email to validate this token.

Check the "Settings" section on the app or admin web (https://admin.nearkey.io) to see this token.

List locks
----------

To list all locks this user can manage:

.. code-block:: shell

    curl -X GET -H "Authorization: TOKEN xxxxxxxxxxxxxxxxxx" https://api.nearkey.io/locks?summary=true

.. note::
    You can remove ``?summary=true`` from the URL to get full data (query will be slower)

List keys on a lock
-------------------

To list all keys for a lock with id ABC123:

.. code-block:: shell

    curl -X GET -H "Authorization: TOKEN xxxxxxxxxxxxxxxxxx" https://api.nearkey.io/locks/ABC123/acl

.. warning::
    Lock id must be URL encoded

.. note::
    You can remove ``?summary=true`` from the URL to get full data (query will be slower)

Create/modify keys
------------------

To create (or modify) a key for a user on lock ABC123:

.. code-block:: shell

    curl -X POST -H "Authorization: TOKEN xxxxxxxxxxxxxxxxxx" -d '{"email":"user@example.com", "name":"User Name", "permissions":["a0"], "start":"2020-01-01T04:05:06", "end":"2031-01-01T04:05:06"}' https://api.nearkey.io/locks/ABC123/acl

.. warning::
    Lock id must be URL encoded

Delete key
----------

To delete a key for user@example.com on lock ABC123:

.. code-block:: shell

    curl -X DELETE -H "Authorization: TOKEN xxxxxxxxxxxxxxxxxx" https://api.nearkey.io/locks/ABC123/acl/user%40example.com

.. warning::
    Lock id & email must be URL encoded