diff --git a/Quickstart.md b/Quickstart.md index 9a2c0a9..ad0ada3 100644 --- a/Quickstart.md +++ b/Quickstart.md @@ -55,28 +55,37 @@ Note that `flask` is a required dependency to run the web server (``pip install $ platypush ``` +If you want to use the web API you will first have to create a user through the web interface - just head to `http://your-host:8008/` and create the user. +You will then have to generate a token for your new user that can be used for API calls. You can either do it from the web panel (Settings -> Generate token) or command line: + +```shell +curl -XPOST -H 'Content-Type: application/json' -d ' + { + "username": "your-user", + "password": "your-pass" + } +' http://localhost:8008/auth +``` + +You can then store this token in an environment variable (e.g. `$PP_TOKEN`) and include it in your API calls over the `Authentication: Bearer` header. + Note: if you have authentication issues with the Hue bridge, press the physical connect button on the bridge and restart the application. 6. Try to send commands to your lights: ```shell -curl -XPOST -H 'Content-Type: application/json' \ - -d '{"type":"request", "target":"your_device_id", "action":"light.hue.on"}' \ +curl -XPOST \ + -H 'Content-Type: application/json' \ + -H "Authentication: Bearer $PP_TOKEN" \ + -d '{"type":"request", "action":"light.hue.on"}' \ http://localhost:8008/execute ``` -Replace `your_device_id` with your hostname (it's the default Platypush device ID) - just type `hostname` in your command line to get it. You can also override the device ID via configuration: - -```yaml -device_id: my_new_device_id -``` - Your lights should have turned on - congratulations! Note that each request has: - The `type=request` field set -- The target device_id - The action name. It will be the plugin package name followed by the name of the method in its main class, in this case `light.hue.on` - An optional key-valued list of method arguments named `args` @@ -95,7 +104,7 @@ A Platypush response will always have a structure like this: } ``` -7. You can optionally set up via configuration a token to authenticate your calls to the server: +7. Another way to set an authentication token is by creating a global token in your `config.yaml`: ```yaml token: your_authentication_token @@ -106,6 +115,7 @@ If configured, the calls to the service will require this bearer token to be pro - As a query string parameter (`?token=your_authentication_token`) - As an HTTP header (`X-Token: your_authentication_token`) - At the root of your JSON request (attribute name: `token`) +- On the `Authentication: Bearer` HTTP header. The web interface will also require basic HTTP authentication through this token. @@ -117,6 +127,7 @@ Note that if you configured a token you'll be promped with a basic HTTP authenti ```shell curl -XPOST -H 'Content-Type: application/json' \ + -H "Authentication: Bearer $PP_TOKEN" \ -d '{"type":"request", "target":"your_device_id", "action":"light.hue.on", "args": {"groups":["Bedroom"]}}' \ http://localhost:8008/execute ``` @@ -203,6 +214,7 @@ Restart Platypush and test out the plugin with a curl call: ```shell curl -XPOST -H 'Content-Type: application/json' \ + -H "Authentication: Bearer $PP_TOKEN" \ -d '{"type":"request", "target":"your_device_id", "action":"weather.forecast.get_current_weather"}' \ http://localhost:8008/execute ```