From 58eed37a06da111b8b22378ad2511e8a793b1c69 Mon Sep 17 00:00:00 2001 From: "Kali Kaneko (leap communications)" Date: Mon, 12 Dec 2016 03:11:56 +0100 Subject: [docs] add doc about authentication header --- docs/core/index.rst | 99 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 59 insertions(+), 40 deletions(-) diff --git a/docs/core/index.rst b/docs/core/index.rst index bd70d36..5b33d82 100644 --- a/docs/core/index.rst +++ b/docs/core/index.rst @@ -31,45 +31,48 @@ Resources Following is a list of currently available resources and a brief description of each one. For details click on the resource name. -+-----------------------------------+---------------------------------+ -| Resource | Description | -+===================================+=================================+ -| ``POST`` :ref:`cmd_core_version` | Get Bitmask Core Version Info | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_core_stats` | Get Stats about Bitmask Usage | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_core_status` | Get Bitmask Status | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_core_stop` | Stop Bitmask Core | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_prov_list` | List all providers | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_prov_create` | Create a new provider | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_prov_read` | Get info about a provider | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_prov_del` | Delete a given provider | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_user_list` | List all users | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_user_active` | Get active user | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_user_create` | Create a new user | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_user_update` | Update an user | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_user_auth` | Authenticate an user | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_user_logout` | End session for an user | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_keys_list` | Get all known keys for an user | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_keys_insert` | Insert a new key | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_keys_del` | Delete a given key | -+-----------------------------------+---------------------------------+ -| ``POST`` :ref:`cmd_keys_export` | Export keys | -+-----------------------------------+---------------------------------+ +**By default, all the resources need authentication**. An asterisk next to it +means that it does not need an authentication header. + ++------------------------------------+---------------------------------+ +| Resource | Description | ++====================================+=================================+ +| ``POST`` :ref:`cmd_core_version` * | Get Bitmask Core Version Info | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_core_stats` * | Get Stats about Bitmask Usage | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_core_status` | Get Bitmask Status | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_core_stop` | Stop Bitmask Core | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_prov_list` * | List all providers | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_prov_create` * | Create a new provider | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_prov_read` * | Get info about a provider | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_prov_del` | Delete a given provider | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_user_list` | List all users | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_user_active` | Get active user | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_user_create` * | Create a new user | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_user_update` | Update an user | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_user_auth` * | Authenticate an user | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_user_logout` | End session for an user | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_keys_list` | Get all known keys for an user | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_keys_insert` | Insert a new key | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_keys_del` | Delete a given key | ++------------------------------------+---------------------------------+ +| ``POST`` :ref:`cmd_keys_export` | Export keys | ++------------------------------------+---------------------------------+ .. _cmd_parameters: @@ -306,4 +309,20 @@ JSON-encoded data to the POST. API Authentication ================== -(TBD) Most of the resources in the API are protected by an authentication token. +Most of the resources in the API are protected by an authentication token. +To authenticate the request, the ``Authentication`` header has to be added to +it. You need to pass a ``Token`` field, with a value equal to the concatenation of +the username and the local session token that you have received after the +authentication call, base64-encoded:: + + + $ curl -X POST localhost:7070/API/core/stop + $ Unauthorized + + >>> import base64 + >>> base64.b64encode('user@provider.org:52dac27fcf633b1dba58') + 'dXNlckBwcm92aWRlci5vcmc6NTJkYWMyN2ZjZjYzM2IxZGJhNTg=' + + $ curl -X POST localhost:7070/API/core/stop -H 'Authentication: Token dXNlckBwcm92aWRlci5vcmc6NTJkYWMyN2ZjZjYzM2IxZGJhNTg=' + $ {'shutdown': 'ok'} + -- cgit v1.2.3