The Senfi platform offers several options for integrations with external systems. This document aims to provide all of the information needed for developers to use Senfi's resources.

Senfi API uses OAuth2 to authenticate requests. Authenticating via OAuth2 requires the following steps:

1. Create an API Key
2. Generate a token
3. Make authenticated requests to the Senfi API

Create an API Key in Senfi CMS. This is a one-time operation. You will be provided your API key and its Secret. Please note this information down, as they will be required for the next step.

After you have created your API key, you must make a call to obtain an access token using the Token API call operation. The operation requires the following parameters:

• client_id - Your API Key
• client_secret - The Secret of your API Key
• grant_type - This must be set to client_credentials

On successful authentication, the response will return an access token and specify how long the token is valid for. You should reuse the bearer token until it is expired. When the token is expired, make the Token API call again to generate a new one.

{
    "access_token": "eea7f833-3117-4615-b5c5-04917bfa7e50",
    "expires_in": 3599,
    ".expire": "2020-10-20T07:18:34.009Z"
}

For subsequent API calls, you will need to set request headers with the OAuth2 access token to authenticate yourself.

{
    "Authorization": "Bearer eea7f833-3117-4615-b5c5-04917bfa7e50"
}

All URLs referenced in the documentation have the following base:

https://api.senfi.io/webservice/1/1

Most of the parameters and data accompanying your requests will be contained in the body of the HTTP request.

The Senfi API accepts JSON in the HTTP request body. No other data format (e.g., XML) are supported.

After receiving your request, the API sends back an HTTP code and a response in JSON.

The API uses standard HTTP status codes to indicate the success or failure of the API call.

In cases of failure, the body of the response contain an error code with a corresponding error message to indicate details of the error:

{
    "success": "false",
    "errcode": "invalid_argument",
    "errmsg": "Invalid arguments"
}

The Senfi Subscription API allow you to integrate to Senfi and receive on-going data, event, alarms, log, and command updates. The updates from Senfi are push notifications that will be sent to webhook callback URLs.

Subscriptions and webhooks are tied to the API Key you used to authenticate the subscription and webhook requests. You can only set one Webhook per API Key, and all subscriptions made with the API Key will be sent to that webhook.

You will need a server that:

• Supports IPV4
• Accept incoming POSTs on port 80 or 443
• Provides a supported, non-wildcard, verified certificate.
• Uses a CN or SAN that matches the domain you’ve supplied on setup
• Supplies all intermediate certificates to complete a verification chain

After you have created your webhook, you must make a call to the Set or Remove Webhook API call to register your webhook with Senfi.

To unregister your webhook from Senfi, make the call with webhook set to `null.

Use the following subscription endpoints to subscribe data to be received by your webhook

• Subscribe to measurements
• Subscribe to events
• Subscribe to alarms
• Subscribe to log messages
• Subscribe to command inform

The format of subscribed data that Senfi will send to your webhook are documented in the Callback section of the respective subscribe endpoints and also the Data Structure section.

An official SDK library for Senfi API is available for Node.js. However, no SDK is required to use the API.

Installation and usage instructions can be found in the senf-node Github repository . SDK code examples are included in these docs.

Obtain Bearer token by OAuth2 authentication

Webhooks are used by Senfi to send subscribed measurement, event, alarm command or log data