Skip to main content

Ecatcher Online Help

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.

    clip0002.png

    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:

    clip0003.png
    1. The list of existing tokens

    2. 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

    1. Inside the API token configuration page, click on the New token button.

    2. 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.

      clip0005.png
    3. 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.

    4. Click OK to create the API token. The next window will show the new token.

      clip0006.png
    5. 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

    1. Inside the API token list, select the API token you want to change and click on the Modify button.

      clip0011.png
    2. 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.

      clip0012.png

    Delete API Token

    1. Inside the API token list, select the API token you want to remove and click on the Delete button.

      clip0009.png
    2. A Delete Token confirmation will pop-up.

      clip0008.png
    3. Click Yes to remove definitively the token.

    Renew API Token

    1. Inside the API Token list, select the API token you want to renew and click on the Renew button.

      API_renew.png

      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.

    2. A Renew Token confirmation will pop-up:

      clip0010.png
    3. 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.

    clip0013.png