Overview

EDGEHOG Device Management APIs allow you to create and manage content on the EDGEHOG platform to manage your fleet of devices also from your company application. The main features accessible from the Web Control Panel are available through Public APIs such as Models creation, Devices creation, update campaigns, etc.

This documentation will help developers who want to integrate EDGEHOG services inside their workflow.

EDGEHOG API is organized around REST and uses HTTP verbs and response codes that most clients are familiar with.

All requests should be made over HTTPS. Our communication standard is JSON, both for successful and error responses.

The Endpoint to reach or call our API library is: https://edgehog.cloud/api/v1​

Security

We take security VERY seriously!

EDGEHOG API uses the Resource Owner Password Credentials Grant flow of OAuth 2.0 for authentication and allows applications to submit authenticated requests on behalf of individual EDGEHOG users using the access credentials. In exchange for valid credentials will be returned an access token in the JSON Web Token (JWT) format.

Once received the valid access token, you simply need to include it with all of your EDGEHOG requests in the authorization header as follows:

Authorization: Bearer <jwt.token>

The bearer token is your key to accessing all of your resources via EDGEHOG API. Keep it safe.

​TLS must be used in all EDGEHOG API interactions, calls made without TLS will be rejected. Requests made without authentication will also be rejected.

Limitation and Suggestions

• Tokens generated with APIs, are associated with the single EDGEHOG account and they inherit the privileges they are associated with.

• Tokens MUST be generated in a secure/safe environment. We HIGHLY discourage the creation of tokens within your front end. Violation of this recommendation could result in the temporary suspension of the service.

• Secret keys must never be made public.

• Our systems limit the requests to a maximum of 60 requests every minute, coming from the same authenticated user or the same IP/domain. The response header contains the limit, the remaining available requests, and the time in which the counter resets (in seconds).

• Each token is valid for a fixed time (1 hour), for security reasons. After this expiration time, the system will automatically revoke the token making it invalid. To generate a new token can be used the refresh API (using the old one) or the login API using credentials

Request Methods

HTTP Status codes

All responses/errors are returned in the form of JSON with a type and optional message.

Success codes

Request Error codes

Authorization errors codes

Server errors codes

Documentation

For sharing the EDGEHOG API documentation we have chosen to use the Swagger Hub platform, which allows the developer to have all the necessary tools to set up his code quickly through examples and ready-made parts of code. For example, you can export, from the swagger description file we provide, ready-made clients in some languages, or test stub servers. Otherwise, you can only View Documentation of the APIs in a more readable way, using the appropriate button on the page.

Our APIs are divided into different macro-areas environments Authentication, Production, and Management.

Authentication APIs

Here are described the API calls needed for authentication, requesting/refreshing the JWT token, as described in the Security section above.

See the Swagger format documentation at this link:

​https://app.swaggerhub.com/apis/edgehog-iot/Authentication/v1​

Production APIs

Here are described the API calls necessary to automate the production process at your company, before sending the complete devices to the field.

See the Swagger format documentation at this link:

​https://app.swaggerhub.com/apis/edgehog-iot/Production/v1​

Management APIs

Here are described the API calls needed for manage EDGEHOG device already created and available on the field, then all the operations related to the device life cycle (decommissioning, replace gw, reinstall os) and all the OS update campaigns or campaigns related to Docker Applications or Files.

See the Swagger format documentation at this link:

​https://app.swaggerhub.com/apis/edgehog-iot/Management/v1​

Edgehog Portal CLI

On Github, you can find a very useful tool to interact with the EDEGHOG REST API by a command-line interface.

The Edgehog Portal CLI and is available here: https://github.com/edgehog-iot/edgehog-portal-cli​

The tool is developed in Python, you can follow the detailed README to know how to use all the functionalities.

​