Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update authenticate.md #26

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update authenticate.md #26

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 20 additions & 13 deletions howtos/authenticate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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=<<api_key>>"

or as a header ``api_token``:

curl -v -X GET "http://192.168.1.25/v1.0/lock -H "api_token: <<api_key>>"

## 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:

Expand All @@ -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

Expand All @@ -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 <span style="color:red">**for development purposes only!**</span>:
* 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:
Expand All @@ -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.
Expand Down Expand Up @@ -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.
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.
Loading