From 7744f98e759d3479c1eb6b3e0f4f13b18da48987 Mon Sep 17 00:00:00 2001 From: Konrad Sikorski Date: Tue, 9 Jul 2024 10:11:37 +0200 Subject: [PATCH] Update authenticate.md explaint how to use api token on every request and add missing steps to postman automation --- howtos/authenticate.md | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/howtos/authenticate.md b/howtos/authenticate.md index 8a6552c..728a8c3 100644 --- a/howtos/authenticate.md +++ b/howtos/authenticate.md @@ -1,6 +1,6 @@ ![](/assets/github-logo.svg "GitHub Logo") [Edit on Github](https://github.com/tedee-com/tedee-bridge-api/blob/master/howtos/authenticate.md) -Every request requires authentication token. +Every request requires an authentication token. The process of using/generating the authentication token is described below. Bare in mind there are **two types** of Authentication Tokens: @@ -11,19 +11,25 @@ The type of token used by the Bridge API can be selected via the mobile app: ![Selecting API Token type](/howtos/images/token_plain.png "Selecting API Token type") -Depends on the selected type of API token, a relevant ``api_key`` value must be generated and passed as a query or header parameter. +Depending on the selected type of API token, a relevant ``api_key`` value must be attached for every request you send to Bridge API. This can be done either as URI param ``api_token``: + + curl -v -X GET "http://192.168.1.25/v1.0/lock?api_token=<>" + +or as a header ``api_token``: + + curl -v -X GET "http://192.168.1.25/v1.0/lock -H "api_token: <>" ## Encrypted Token For more information or to report issues, visit our [Github](https://github.com/your-repo-path). This type of token provides sufficient security level to the system: -* every request (with a given ``api_key``) can be processed only once due to timestamp value embedded in the ``api_key`` value -* every request will have different ``api_key`` value, effectively, the entire request string will be different +* every request (with a given ``api_key``) can be processed only once due to the timestamp value embedded in the ``api_key`` value +* every request will have a different ``api_key`` value, effectively, the entire request string will be different * the internal token string will never be revealed The ``api_key`` value needs to be calculated independently for every request, based on: * ``token`` - taken from the Tedee app -* ``timestamp`` - a current date & time as a "big" integer value in milliseconds (also known as: epoch time) +* ``timestamp`` - a current date & time as a "big" integer value in milliseconds (also known as epoch time) The formula pattern to get the ``api_key`` value is: @@ -42,7 +48,7 @@ Let's say the ``token`` is: BE9xnPnGfVUS1691058833000 -2. Calculate hash (SHA256) for the above string +2. Calculate a hash (SHA256) for the above string e59d9763edc6e59f2faccf9a769e5cf170d68439c3fd67afae5e3e72d0463a71 @@ -56,10 +62,10 @@ The last string you received is your ``api_key`` value. ## Plain Token This type of token **does not** provide sufficient security level to the system and can be used **for development purposes only!**: * the Bridge API token **will be revealed!** -* every request of the same kind will look the same and can be processed **multiple of times** +* every request of the same kind will look the same and can be processed **multiple times** * malicious software or user can take control of the Locks by sniffing the traffic in the local network -The ``api_key`` value for this token type is just the token taken from Tedee app +The ``api_key`` value for this token type is just the token taken from the Tedee app ### For example: Let's say the ``token`` is: @@ -70,7 +76,6 @@ Let's say the ``token`` is: BE9xnPnGfVUS - ## Postman Automation For testing purposes, [Postman](https://www.postman.com) can be configured to use both types of tokens (Encrypted and Plain) by adding several scripts and variables in the relevant places. Follow the steps described below if you want to do so. @@ -100,11 +105,13 @@ Follow the steps described below if you want to do so. eval(pm.globals.get('SECURE_TOKEN_SCRIPT')); -3. Go to a selected endpoint -> Authorization tab and enter "{{API_KEY}}" into the value text field as shown below: +3. Go to a selected endpoint -> Authorization tab and set: + - the ``Type`` to "API Key" + - the ``Key`` to "api_token" + - the ``Value`` to "{{API_KEY}}" ![Set api_key value](/howtos/images/postman_auto_auth.png "Set api_key value") -4. Done. - Now you can send requests with encrypted token mode without the need of manual calculation every time! +4. Done. Now, you can send requests with encrypted token mode without manual calculation every time! ### Note! -Bare in mind that every time you change the token type in Tedee app then you must change the **API_TOKEN_MODE** current value accordingly. \ No newline at end of file +Keep in mind that every time you change the token type in the Tedee app, you must change the **API_TOKEN_MODE** current value accordingly.