REST APIs

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
Method
Description
GET
A request of one or multiple elements
POST
Create an element
PUT
Modify or action on an element
DELETE
Delete an element
HTTP Status codes
All responses/errors are returned in the form of JSON with a type and optional message.
Success codes
Code
Description
200
Success - Request successfully completed
201
Created - Request successfully created (POST calls)
204
Success - No Content
Request Error codes
Error Code
HTTP Status
Error
1000
400
Record not found
1100
400
Invalid filter
2000
400
Unique constraint violated
2100
422
Invalid input
2200
415
Invalid image
2201
415
Invalid file
2300
409
Possible stale data
2400
400
Invalid request
2500
400
Invalid argument
Authorization errors codes
Error Code
HTTP Status
Error
3000
401
Invalid credentials
3100
400
User account exception
3200
400
User group exception
3300
403
Missing privilege
3400
422
Security lock exception
3500
400
JWT exception
3600
429
User's account is locked
3700
403
Authorization exception
Server errors codes
Error Code
HTTP Status
Error
4100
500
Missing certificate
4200
500
Invalid provider
5100
500
External API exception
5200
500
External API timeout
5300
500
IoT broker exception
9999
503
Maintenance mode enabled
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.
​
Local API - Previous
Device Manager Agent local APIs
Last modified 2yr ago
Copy link
On this page
Overview
Security
Request Methods
HTTP Status codes
Documentation
Authentication APIs
Production APIs
Management APIs
Edgehog Portal CLI