Talk2m API
API Tokens
What is an API Token ?
API Tokens are secure IDs that allow applications to be authenticated when using the Talk2m APIs.
A token is a string of maximum 50 characters (ASCII numbers and letters, uppercase and lowercase).
The Talk2m account administrator creates a token for each application or 3rd party platform that they plan to use.
All tokens are created, referenced, maintained and managed in a list from a specific section of the Account page Ecatcher.
Why use Token instead of user credentials ?
API tokens add an extra layer of security.
API Tokens can only be used as part of Talk2m API calls and cannot be used to gain remote access to any devices on the Talk2m account.
What are API tokens used for?
With the API tokens, all the authentication parameters are replaced by:
- t2mtoken
Important
For security reasons, this parameter is only available in HTTP POST queries.
To preserve compatibility with existing applications that do not support the t2mtoken parameter, the parameters t2maccount, t2musername & t2mpassword can be used with a token as below:
- t2maccount = Account Name
- t2musername = "t2m-api-token"
- t2mpassword = Token
Notice
This will only work if in the application POST HTTP queries have been used.
GET HTTP requests will receive an HTTP 405 – Method Not Allowed error.
Datamailbox API SDK
The DMWeb API is a RESTful web service combined with the Talk2m service DataMailbox which allows easy retrieval of Ewon gateway historical data.
For more information, you can read to the related docmentation. RG-005-00 - DMWeb API for DataMailbox explains evertyhing you need to know if you want to use the DMWeb API technology.
You can also find lots of information on our dedicated developer website: https://developer.ewon.biz/content/dmweb-api
Token Management
The tokens are managed inside the Advanced Settings of the Accounts page.
The number of currently defined tokens is indicated as a reminder in the API Tokens section.
To open the API Token configuration page, click on the Manage... button. A modal dialog window opens containing:
The list of existing tokens
Buttons:
- New token
- Modify
- Delete
- Renew
Column | Description |
Name | The name you specified for the token |
Token prefix | The prefix of the token. For security reasons, the token itself can only be retrieved during the creation process of the token. The display of the prefix here allows to identify the token later on. |
Device Pool | The Device pool linked to the token. The token will give access to the data of all Ewons contained inside this pool. |
API | The type of API. Currently fixed to “DataMailbox” |
Last used | The date when the API was last used. For implementation reasons, the time of modification is not displayed, only the date. This is more accurate and avoids to update the DB for each API call. |
Note
Talk2m free+ accounts do not have pools, therefore, for free accounts the Device_pool column is not displayed.
Add API Token
Inside the API token configuration page, click on the New token button.
Specify a Name to identify your token. The name could for example contain information of the application or the partner who will use the token to retrieve the data.
Check the Read only option next to DataMailbox Access to create a token that cannot delete data out of the DataMailbox.
Notice
If the Read only option is checked, delete and reset are not allowed.
Click OK to create the API token. The next window will show the new token.
Use the Copy to clipboard button to retrieve the token.
Warning
This is the only time you will have access to the API token.
Once the window is closed, you will no longer be able to display it. If you forgot the token you’ll need to renew it.
Modify API Token
Inside the API token list, select the API token you want to change and click on the Modify button.
In the pop-up window allows to change the Name and the Device pool (only for Pro accounts) associated to the existing API Token.
You can also change the DataMailbox access type.
Delete API Token
Inside the API token list, select the API token you want to remove and click on the Delete button.
A Delete Token confirmation will pop-up.
Click Yes to remove definitively the token.
Renew API Token
Inside the API Token list, select the API token you want to renew and click on the Renew button.
The Renew button combines the Delete button with the New token button.
The information of the token remains the same, but a new token is generated.
A Renew Token confirmation will pop-up:
Click Yes to generate a new token.
API Token Change Log
All token operations are logged in the Account Logs, including the user who performed the operation.
