MyThings API Overview

Important prerequisite

You can start using the MyThings API only if you have a valid and active MyThings subscription. For new customers looking to subscribe to MyThings you can contact us here.

MyThings is a management platform that holds a set of powerful APIs which allows you to easily manage the sensors connected to your IoT network. MyThings gives u an overview of all sensors and their connection status with the install base. Link logical actions to the sensors, and your business processes will run smoother than ever. This way, IoT can truly bring added value to your company.

• Easy to manage IoT platforms
• Possible for any type of network
• Visualization and monetization of data
• Integration with your company's back-end processes

Technical info

MyThings API supports the following functionalities:

• Provisioning API's (Add, Delete, Update things)
• Downlink API's (Send data towards your LoRa things)
• Query API's (Get historical data from your things)
• Status API
• Stream data API

Integrate

CloudEngine provides MyThings inbound modules allowing transformation and enrichment on incoming IoT data flows, flexible outbound endpoints with HTTP and MQTT as well as integration with IoT platforms such as Microsoft Azure, SAP IoT Cloud and Waylay.

For more info on activation and start configuring this API, read more below.

MyThings API Introduction

The MyThings integration on the EnCo platform covers two major functionalities:

1. API to allow for an easy integration of the MyThings functionalities into you own application with a simple HTTP request.
2. A CloudEngine inbound endpoint for an easy integration of the data generated by your LoRaWAN IoT devices in visual flows and scripts in CloudEngine.

MyThings API for the following functionalities are exposed:

• Provisioning API (Add, Delete, Update things)
• Downlink API (Send data towards your LoRa things)
• Query API (Get historical data from your things)
• Status API

Next to the API's above there is also a Stream data API and the Uplink data API.

Stream data API

In order to receive the real-time data from your things you need to setup a data stream towards your application endpoint in the Stream Definition setup on MyThings. For more info on stream data stream please check Stream data API or the MyThings user manual that is available via the MyThings portal. When linking your MyThings and EnCo account, please also note that a new Stream of type “CLOE” is automatically created on MyThings. This stream enables the usage of the MyThings inbound endpoint on CloudEngine.

Uplink data API

The Uplink data API will be available soon.

Getting Started

Introduction

You have some IoT Things? Do you have an account on MyThings and Enabling Company? Then you are ready to start using our MyThings API! Below are some quick pointers on how to get started.

If you still need a device and/or account, you can obtain one using the links below:

• MyThings Account: https://mythings.proximus.be (please contact your sales or send a mail to iot@proximus.com in order to get access)
• Proximus API Solutions Account: https://market.enco.io
• Device catalogue: Please contact your sales or send a mail to iot@proximus.com in order to get the latest catalogue.

High Level Overview

Activating the MyThings API for your existing MyThings account

Currently you can only use the MyThings API if you have an existing MyThings account.

1.Create an account on the Proximus API Solutions marketplace and go to the MyThings API asset.

2. Subscribe to the Existing MyThings Plan.

3. You will receive an invitation mail from noreply@clearmedia.be with a link to connect your Enabling company account with your existing MyThings account.

Open link from mail

Please make sure that you open the link in the same browser (other tab) than where you have logged into the enco.io account.

Before linking the account

1. Please make sure that the existing company you want to link is a main company and not a sub company.
2. Please make sure that the MyThings user you use to link has a **superadmin **account.
3. Please make sure that no other user has already linked to your company. The link can only be done once per main company.

Only press "Log in" once

When your login is correct, is a superadmin to for a main company that was not linked before it will take a few seconds to link the accounts. When the linking is done you will the screen below.

4. This will grant access to the Endpoint and API console, where you can try out the MyThings API.

You can use the temporary API key from the console or the permanent one from the project/ token management (General API tokens).

You can test the API's via the API console. A curl example is provided here.

In the near future you will also be able to have access to the MyThings API if you have no existing MyThings account. It will be possible to order a new MyThings account via the Marketplace.

Provisioning API's

The MyThings provisioning API allow to manage your things (add, delete, update, …), your LoRa device addresses for ABP things and retrieve some thing provisioning information.

Base url: https://api.enco.io/mythings/1.1.0

The access_token should be retrieved via the authentication API.

/things GET
/things POST
/things/{thingIdentifier} DELETE
/things/{thingIdentifier} GET
/things/{thingIdentifier} PUT
/things/{thingIdentifier}/deprovision DELETE
/things/{thingIdentifier}/provision POST
/things/{thingIdentifier}/tags PUT
/things/{thingIdentifier}/type GET
/things/{thingIdentifier}/{containerFriendlyName} DELETE
/basestations/{basestationId} PUT
/deviceaddress GET
/deviceaddress/assign PUT
/deviceaddress/reserve GET
/connectivityplans GET
/thingtypes GET
/vendors GET
/streamdefinitions GET
/streamdefinitions POST
/streamdefinitions PUT
/streamdefinitions DELETE

things

GET /things

Description

Retrieve a list of things based on the given search criteria. All parameters are optional. If no parameters are defined all the things you own and all public things will be returned.

Parameters

Responses

Consumes

• application/json

Produces

• application/json

POST /things

Description

Create a new thing of any type and if needed provision it on the network.

Parameters

Responses

Consumes

• application/json

Produces

• application/json

Example

POST /things ABP

{
    "connectivityType":"LORA.ABP",
    "thingIdentifier":"1234ABCDABCD3333",
    "companyId":77,
    "thingName":"testmythingname",
    "description":"mythingsdescription",
    "isPublic":false,
    "thingTypeId":33,
    "longitude":"mythingslongitude",
    "latitude":"mythingslatitude",
    "locationFN1":"mythingsfn1",
    "locationFN2":"mythingsfn1",
    "connectivityPlan":"pxs-iot-cs/96-up-transactions-0-down",
    "deviceAddress":"ABCd12AA",
    "keys":{
        "applicationSessionkeys":[
                            {"applicationSessionKey":"11111234123412341234123412341243","port":"1"}
                            ],
        "networkSessionKey":"44341234123412344444123412341241"},
    "tags":["tag1","tag2","taggedyTagTag"],
    "motionIndicator":"Vehicle speed"
}

POST /things OTAA

{
    "connectivityType":"LORA.OTAA",
    "thingIdentifier":"ABCDAB22ABCDABC2",
    "companyId":162,
    "thingName":"mythingname",
    "description":"mythingsdescription",
    "isPublic":false,
    "thingTypeId":10,
    "longitude":"mythingslongitude",
    "latitude":"mythingslatitude",
    "locationFN1":"mythingsfn1",
    "locationFN2":"mythingsfn1",
    "connectivityPlan":"pxs-iot-cs/288-up-transactions-24-down",
    "keys":{
        "applicationKey":"12341234123412341234123412341234",
        "applicationEUI":"1234123412341234"
    },
    "motionIndicator":"Random"
}

POST /things ETHERNET (available soon)

{
    "connectivityType":"ETHERNET",
    "thingIdentifier":"ABCDAB22ABCDABC2",
    "companyId":376,
    "thingName":"mythingname",
    "description":"mythingsdescription",
    "isPublic":false,
    "thingTypeId":24,
    "longitude":"mythingslongitude",
    "latitude":"mythingslatitude",
    "locationFN1":"mythingsfn1",
    "locationFN2":"mythingsfn2",
    "serialNumber":"1234123412341234"
}

DELETE /things/{thingIdentifier}

Description

The thing is completely removed including a deprovisioning of the resource.

Parameters

Responses

Consumes

• application/json

Produces

• application/json

GET /things/{thingIdentifier}

Description

Get the details of a specific thing using his thing identifier as key.

Parameters

Responses

Consumes

• application/json

Produces

• application/json

PUT /things/{thingIdentifier}

Description

Get the details of a specific thing using its thing identifier as key.

Parameters

Responses

Consumes

• application/json

Produces

• application/json

Example

PUT /things/{thingIdentifier} OTAA

{
    "isPublic":false,
    "thingName":"updatedThingName",
    "description":"updatedDescription",
    "tags":["tag1","tag2","tag3","tag4","tag5","tag6"],
    "latitude":"2",
    "longitude":"50",
    "locationFN1":"updateFn1",
    "locationFN2":"updateFn2",
    "keysLoRaOTAA":{
        "applicationKey":"55551234123412341234123412341234",
        "applicationEUI":"4444123412344444"
    }
}

PUT /things/{thingIdentifier} ABP

{
    "isPublic":false,
    "thingName":"updatedThingName",
    "description":"updatedDescription",
    "tags":["tag1","tag2","tag3","tag4","tag5","tag6"],
    "latitude":"2",
    "longitude":"50",
    "locationFN1":"updateFn1",
    "locationFN2":"updateFn2",
    "keysLoRaABP":{
      "applicationSessionkeys":[
            {
              "applicationSessionKey":"11111234123412341234123412341243",
              "port":"1"
            }
      ],
      "networkSessionKey":"44341234123412344444123412341241"
   }
}

PUT /things/{thingIdentifier} ABP (remove applicationSessionKeys)

{
    "keysLoRaABP":{
        "applicationSessionkeys":[{}]
        }
}

PUT /things/{thingIdentifier} ETHERNET (available soon)

{
    "isPublic":false,
    "thingName":"ethernetDevice",
    "description":"updateDescription",
    "tags":["tag1","dummyTag","anotherTag","tag2","tag3"],
    "latitude":"2",
    "longitude":"50",
    "locationFN1":"fn1",
    "locationFN2":"fn2"
}

DELETE /things/{thingIdentifier}/deprovision

Description

Remove a thing from the network only. This only applies for LoRa things.

Parameters

Responses

Consumes

• application/json

Produces

• application/json

POST /things/{thingIdentifier}/provision

Description

Add a thing to the network only. This only applies for LoRa things.

Parameters

Responses

Consumes

• application/json

Produces

• application/json

PUT /things/{thingIdentifier}/tags

Description

Add a tag to a thing.

Parameters

Responses

Consumes

• application/json

Produces

• application/json

Example

PUT /things/{thingIdentifier}/tags (single tag)

["dummyTag"]

**PUT /things/{thingIdentifier}/tags (multiple tags)

["tag0","tag1","tag3","tag4"]

GET /things/{thingIdentifier}/type

Parameters

Responses

Consumes

• application/json

Produces

• application/json

DELETE /things/{thingIdentifier}/{containerFriendlyName}

Parameters

Responses

Consumes

• application/json

Produces

• application/json

basestations

PUT /basestations/{basestationId}

Description

Add a longitude and latitude to a LoRa base station

Parameters

Responses

Consumes

• application/json

Produces

• application/json

Example

PUT /basestations/{id}

{
  "companyId": 987,
  "latitude": "50",
  "locationName": "Wall street",
  "longitude": "2"
}

deviceaddress

GET /deviceaddress

Description

For LoRa ABP things only. It gives the next available device addresses that are in the state “reserved” for your company.

Parameters

Responses

Consumes

• application/json

Produces

• application/json

PUT /deviceaddress/assign

Parameters

Responses

Consumes

• application/json

Produces

• application/json

Example

PUT /deviceaddress/assign

{
  "companyId": 987,
  "devAddresses": [
    "07FFF001"
  ]
}

GET /deviceaddress/reserve

Parameters

Responses

Consumes

• application/json

Produces

• application/json

connectivityplans

GET /connectivityplans

Responses

Consumes

• application/json

Produces

• application/json

thingtypes

GET /thingtypes

Responses

Consumes

• application/json

Produces

• application/json

vendors

GET /vendors

Responses

Consumes

• application/json

Produces

• application/json

streamdefinitions

GET /streamdefinitions/{streamDefinitionId}

Responses

Consumes

• application/json

Produces

• application/json

createStreamDefinition

POST /streamdefinitions

Parameters

Responses

Consumes

• application/json

Produces

• application/json

Example

Make sure that value of property template has a backslash ( \ ) before every double-quote character ( " ). See below for a working example.

The "mutualAuth":true is available when it's activated by Proximus on company level. By default its not activated. POST /streamdefinitions

{
    "active": false,
    "autoLink": true,
    "companyId": 987,
    "contentType": "JSON",
    "basicAuth": false,
  "mutualAuth": false,
    "name": "MyStream",
    "template": "{\"timestamp\": \"%timestamp[yyyy-MM-dd HH:mm:ss.SSS]%\",\"company\": \"%companyname%\",\"macaddress\": \"%thingidentifier%\",\"container\": \"%container%\",\"location\": \"%locationfriendlyname1%\",\"value\": \"%value%\",\"description\": \"PirSensor\"}",
    "type": "DECODED",
    "url": "https://my.streaming.url"
}

PUT /streamdefinitions/{streamDefinitionId}

Responses

Consumes

• application/json

Produces

• application/json

Example

PUT /streamdefinitions/{streamDefinitionId}

{
    "active": true,
    "headers":[
    {
      "key":"Content-Type",
      "value":"application/json"
    }
  ],
  "password": "admin",
  "userName": "admin"
}

DELETE /streamdefinitions

Responses

Consumes

• application/json

Produces

• application/json

Downlink API's

The MyThings downlink API allow to send data your LoRa things.

Base url: https://api.enco.io/mythings/1.1.0

The access_token should be retrieved via the authentication API. See the Authentication page

/downlink POST
/downlink/template/{templateUid} POST
/configurationtemplates GET

downlink

POST /downlink

Parameters

Responses

Consumes

• application/json

Produces

• application/json

Example

POST /downlink

{
    "devEUI":"9999888877776666",
    "fPort":"9",
    "payload":"04FD20D9",
    "encrypted":"0",
  "ack": 1
}

POST /downlink/template/{templateUid}

Parameters

Responses

Consumes

• application/json

Produces

• application/json

Example

POST /downlink/template/{templateUid}

{
    "thingIdentifiers":[
        "BACBADBADADBADAD",
        "AAAAAAAAAAAAAAAA"
    ]
}

configurationtemplates

GET /configurationtemplates

Responses

Consumes

• application/json

Produces

• application/json

Query API's

The MyThings query API allow your application to retrieve data from your things (historical data) and also from your base stations and business rules.

Pricing for the query API's can be found on the enco marketplace.

Base url: https://api.enco.io/mythings/1.1.0

The access_token should be retrieved via the authentication API.

/things/{thingIdentifier}/locations GET
/things/{thingIdentifier}/logs/decoded GET
/things/{thingIdentifier}/logs/decoded/count GET
/things/{thingIdentifier}/logs/network GET
/things/{thingIdentifier}/logs/network/count GET
/things/{thingIdentifier}/type/{containerName}/values GET
/basestations GET
/basestations/{basestationId} GET
/businessrules GET
/businessrulestriggered GET
/businessrulestriggered/{businessRuleId} GET
/containerdefinitions GET

things

GET /things/{thingIdentifier}/locations

Parameters

Responses

Consumes

• application/json

Produces

• application/json

GET /things/{thingIdentifier}/logs/decoded

Parameters

Responses

Consumes

• application/json

Produces

• application/json

GET /things/{thingIdentifier}/logs/decoded/count

Parameters

Responses

Consumes

• application/json

Produces

• application/json

GET /things/{thingIdentifier}/logs/network

Parameters

Responses

Consumes

• application/json

Produces

• application/json

GET /things/{thingIdentifier}/logs/network/count

Parameters

Responses

Consumes

• application/json

Produces

• application/json

GET /things/{thingIdentifier}/type/{containerName}/values

Parameters

Responses

Consumes

• application/json

Produces

• application/json

basestations

GET /basestations

Responses

Consumes

• application/json

Produces

• application/json

GET /basestations/{basestationId}

Parameters

Responses

Consumes

• application/json

Produces

• application/json

businessrules

GET /businessrules

Responses

Consumes

• application/json

Produces

• application/json

GET /businessrulestriggered

Responses

Consumes

• application/json

Produces

• application/json

GET /businessrulestriggered/{businessRuleId}

Parameters

Responses

Consumes

• application/json

Produces

• application/json

containerdefinitions

GET /containerdefinitions

Parameters

Responses

Consumes

• application/json

Produces

• application/json

Status API

An API endpoint where the current MyThings status can be retrieved.

Base url: https://api.enco.io/mythings/1.1.0

The access_token should be retrieved via the authentication API.

/status GET

status

GET /status

Description

The overall status of the MyThings API.

Responses

Consumes

• application/json

Produces

• application/json

Stream Definitions

1.Log into MyThings and go to the Settings / Stream Definitions menu

2.Create a new stream definition

Company: The company or sub company you want to configure the stream on.
Type: NETWORK/DECODED/LBS
Stream Name: This is a free field to identify the stream.
Stream URL: This needs to be a valid URL for the endpoint where you want to send the data.

Both HTTP and HTTPS is supported.

• The endpoint needs to return valid http status code (200, 404, 500…) and status message. The status message may not contain variable data (timestamp …) as that will put every failure in a separate line in the stream definition failure and make it hard to reprocess the failed data. (data with the same http status code and status message will be grouped in the stream definition failures).
• Proximus will monitor if incorrect URL’s are configured and can disable streams towards invalid or broken URL’s.
• If the HTTP(S) status code is not returned then there will be a timeout. The stream will be put on “Timeout” for 60 seconds and all data from the things that was send during those 60 seconds will be put in the “stream definition failures” and can be reprocessed manually.

Stream security: you can select “None”, “Basic Authentication” and on request a “Mutual Authentication” option can be enabled (this option is available as a professional service – please contact your sales – documentation on this option is not available here and can be found on MyThings in the documentation menu).
Headers: are optional based on application server header requirements.

IoT Connect

You can define 2 stream definitions per company.

• You can create network stream definition. The format is the Raw XML that we receive from our LoRa network.
• You can create a DECODED or LOCATION stream definition in XML, JSON or FREEFORM with selectable presets. The elements in the JSON depend on the ones that were selected.
• You can select which things are linked to the stream definitions. The thing to stream link can be set manually or automatically.
• You can give the stream a custom name.

Example network stream (XML):

<?xml version="1.0" encoding="UTF-8"?>
<DevEUI_uplink xmlns="http://uri.actility.com/lora">
    <Time>2019-03-22T11:14:30.426+01:00</Time>
    <DevEUI>0011223344000259</DevEUI>
    <FPort>2</FPort>
    <FCntUp>93473</FCntUp>
    <ADRbit>1</ADRbit>
    <MType>2</MType>
    <FCntDn>27080</FCntDn>
    <payload_hex>00</payload_hex>
    <mic_hex>fd80eaf4</mic_hex>
    <Lrcid>00000201</Lrcid>
    <LrrRSSI>-95.000000</LrrRSSI>
    <LrrSNR>6.000000</LrrSNR>
    <SpFact>12</SpFact>
    <SubBand>G0</SubBand>
    <Channel>LC1</Channel>
    <DevLrrCnt>2</DevLrrCnt>
    <Lrrid>FF0107A5</Lrrid>
    <Late>0</Late>
    <LrrLAT>00.223259</LrrLAT>
    <LrrLON>00.972714</LrrLON>
    <Lrrs>
        <Lrr>
            <Lrrid>FF0107A5</Lrrid>
            <Chain>0</Chain>
            <LrrRSSI>-95.000000</LrrRSSI>
            <LrrSNR>6.000000</LrrSNR>
            <LrrESP>-95.973228</LrrESP>
        </Lrr>
        <Lrr>
            <Lrrid>FF010624</Lrrid>
            <Chain>0</Chain>
            <LrrRSSI>-107.000000</LrrRSSI>
            <LrrSNR>-20.000000</LrrSNR>
            <LrrESP>-127.043213</LrrESP>
        </Lrr>
    </Lrrs>
    <CustomerID>100000000</CustomerID>
    <CustomerData>{"alr":{"pro":"LORA/Generic","ver":"1"}}</CustomerData>
    <ModelCfg>0</ModelCfg>
    <InstantPER>0.000000</InstantPER>
    <MeanPER>0.012488</MeanPER>
    <DevAddr>061008D0</DevAddr>
    <TxPower>1.000000</TxPower>
    <NbTrans>1</NbTrans>
</DevEUI_uplink>

Example Decoded stream (JSON):

{
    "companyName": "Proximus Demo",
    "thingName": "Temperature and humidity",
    "thingVersion": "1",
    "thingType": "Temperature and humidity",
    "vendor": "NKE",
    "latitude": "",
    "longitude": "",
    "description": "",
    "locationFriendlyName1": "Brussels Proximus towers",
    "locationFriendlyName2": "",
    "containerFriendlyName": "Temperature",
    "container": "0x0402.0x0000.0.m2m",
    "value": "23.79",
    "postfix": "°",
    "timestamp": "1487187830340",
    "DevEUI": "70B3D5E75E000259",
    "DevAddr": "5E000259",
    "FPort": "6",
    "Fcntup": "22843",
    "Ackbit": "",
    "Adrbit": "1",
    "Fcntdn": "6386",
    "Lrcid": "00000201",
    "Lrrrssi": "-83.000000",
    "Lrrsnr": "8.000000",
    "Spfact": "12",
    "Subband": "G1",
    "Channel": "LC2",
    "Dvlrrcnt": "2",
    "Lrrid": "004A0362",
    "Customerid": "100000136",
    "Customerdata": "{\"loc\":{\"lat\":\"50.860191\",\"lon\":\"4.358177\"},\"alr\":{\"pro\":\"WECO/TPHU\",\"ver\":\"1\"}}",
    "Modelcfg": "0",
    "Batterylevel": "",
    "Batterytime": "",
    "margin": "",
    "payload": "0402000029094b"
}

In order to see some real messages easily you can use an online service like https://hookbin.com and create and endpoint url there. If you fill in that endpoint URL as the stream URL on MyThings, then the data will be send to there where it is visualised. Services like hookbin only keep the URL valid for a very limited time. After you have some example data, please disable the stream or change the URL to your valid server endpoint URL so that the system does not generate stream error mails

Aggregated Containers: You have the option to receive the decoded data in 2 ways. (per container OR aggregated).

If the aggregated option is disabled, then the decode stream will send data on thing container level (one POST per container). If a thing sends one message and it has multiple containers (example: temperature/humidity/battery) then multiple POST’s will be done.

Example:

Message 1
{
  "companyName": "Proximus Demo",
  "DevEUI": "0E7E3464061004A2",
  "container": "temperature",
  "containerfriendlyName": "humidity",
  "value": "22.93",
  "locationFriendlyName1": null,
  "timestamp": "19/09/2019 12:23:48"
}

Message 2
{
  "companyName": "Proximus Demo",
  "DevEUI": "0E7E3464061004A2",
  "container": "humidity",
  "containerfriendlyName": "humidity",
  "value": "52",
  "locationFriendlyName1": null,
  "timestamp": "19/09/2019 12:23:48"
}

If the aggregated option is enabled, then the decode stream will group all containers in 1 message. If a thing sends one message and it has multiple containers (example: temperature/humidity/battery) then only 1 POST’s will be done.

Example:

{
  "companyName": "Proximus Demo",
  "DevEUI": "0E7E3464061004A2",
  "containers": [
    {
      "container": "temperature",
      "containerfriendlyName": "temperature",
      "value": "22.93",
      "postfix": "°C"
    },
    {
      "container": "humidity",
      "containerfriendlyName": "humidity",
      "value": "52",
      "postfix": "%"
    }
  ],
  "locationFriendlyName1": null,
  "timestamp": "19/09/2019 12:23:49"
}

MyThings inbound endpoint for CloudEngine

When linking your MyThings and EnCo account, and if subscribed to the EnCo CloudEngine, you will get access to two new inbound endpoints on CloE:

• MyThings - Data: receives sensor data from devices in your MyThings account. Incoming data can be filtered with tags so that visual flows or scripts can be triggered based on deviceEUI, thing type, company name or any tag associated to your things on MyThings.
• MyThings - Things: receives updates about things such as new things, removed things, provisioned/deprovisioned things. Incoming events can be filtered with tags so that visual flows or scripts can be triggered based on event type, thing identifier, thing type, company name or any tag associated to your things on MyThings.

Documentation about these inbound endpoints are available from within CloudEngine, by clicking on the question marks of each respective endpoint, as shown below:

When selecting The MyThings - Data as input, the stream setup will be done automatically in the MyThings stream definitions.

Definitions

ApplicationSessionKeyResource

BaseStationResponse

Basestationupdaterequest

Company

ConnectivityPlan

ConnectivityPlanResult

Container

ContainerDefinitionDTO

ConfigurationTemplatesResponse

CountResponse

Data

DeviceAddressAssignRequest

DeviceAddressResponse

DownlinkRequest

DownlinkRequestWithTemplate

DownlinkResponse

Error

Link

Location

LocationHistory

Lrr

NetworkData

PageResource«LocationHistory»

PageResource«NetworkData»

PageResource«SensorHistory»

ResponseEntity

Sensor

SensorGroup

SensorHistory

Sort

Type : object

StatusMessageDTO

TechnologyDetails

ThingContainerResource

ThingContainerValueResource

ThingCreateRequest

ThingKeysLoRaABP

ThingKeysLoRaOTAA

ThingResource

ThingTypeDTO

ThingUpdateRequest

VendorDTO

rule

thing

triggeredBusinessRule

triggeredBy

streamrequest

API authentication

API Solutions uses OAuth2 to protect API resources. The OAuth2 specification has become the predominant standard for securing RESTful APIs and identity delegation.

In order to gain access to the resources exposed by your API assets, you will need to pass along a valid OAuth2 bearer access token. Here is how you can generate such a token.

Obtaining your OAuth2 Application Keys

Each project you create through the API Solutions Market will result in the creation of a unique pair of OAuth2 application keys. To retrieve your keys, proceed as follows:

• First, log in and visit your dashboard on the portal. Click the "TOKEN" menu.
• This will result in your application keys to be shown. These keys can be used to access API resources exposed by any API asset to which you subscribed, within the scope of the selected project.

Your application keys are sensitive information; keep them private at all time!

Make sure to store your application keys in a safe way, avoiding them to leak or be stolen by an unintended audience. They are quite sensitive, in that anyone obtaining them will be able to gain access to your assets. In case your application keys would become compromised, contact us through support and we'll revoke them to block access, and provide you with a new pair. This is also the reason why all API traffic should pass through secured HTTP, and why we do not support plain HTTP.

Generating a fresh bearer access token

A bearer access token is a self-contained unique identifier through which you can gain access to API resources. Before elaborating on how you can obtain such type of token, please note that these tokens are valid for a limited time span of 1 hour (or less, if explicitly revoked).

You can obtain a new token by issuing the following request against the server https://api.enco.io :

token POST

Issue a request to https://api.enco.io/token, adding the following headers and body:

Request

curl -X POST \
  'https://api.enco.io/token?grant_type=client_credentials&scope=openid&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&Accept=application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' 

Response payload

{ 
  "scope": "openid", 
  "token_type": "Bearer", 
  "expires_in": {number}, 
  "access_token": {string}
}

The field accesstoken in the response contains your token. The field expiresin will show you the remaining validity of your token, in seconds.

Single active access token
Within the context of a single application, you will only have a single active access token at any time. If you would request a new token using the above request message while the previously issued token has not yet expired, you will get back the previous token. To obtain a new one, revoke the old token; then generate a new one.

Code Samples
To help you getting started on implementing this authentication in your code, you can find some samples on our Github.

Revoking an access token

This procedure should be used when your token has been compromised (leaked, stolen, etc.), or if you want to generate another token, but your old token is still valid.

revoke POST

Issue a request to https://api.enco.io/revoke, adding the following headers and payload:

Request payload

token=<old-access-token-to-be-revoked>&client_id=<app-consumer-key>&client_secret=<app-consumer-secret>

Creating permanent token

You can create permanent tokens from the "TOKEN" menu of your profile's dashboard. Just click on "Add a new token" to create a new permanent token. Several permanent tokens can be created for the same account.

Your permanent token is sensitive information; keep it private at all time!

Make sure to store your permanent tokens in a safe way, avoiding them to leak or be stolen by an unintended audience. They are quite sensitive, in that anyone obtaining them will be able to gain access to your assets. In case a permanent token would become compromised or not needed anymore, delete this token from your "TOKEN" dashbload by clicking on the red cross next to it.

All set to call your API!

Once a valid access token has been generated, it should be added to request messages. The token should be passed in an HTTP header named Authorization, which should be assigned the value of Bearer, followed by a single space, and immediately followed by the access token. Note the single space between ‘Bearer’ and the token.

curl -i -X GET -H "Accept:application/json" -H "Authorization: Bearer <active-access-token>" https://api.enco.io/lora4maker/0.0.1/device