Documentation

Web-API

The Web-API provides endpoints for various operations like connecting/disconnecting a device, retrieving device information and more.

Authentication

For authenticating requests, an activated subscription-key has to be passed as request header:

wuh-iot-subscription-key: <subscription-key>

Available subscription-keys can be viewed via Profile page.

Limitations

The Web-API can not be used for polling data with high frequency, instead, it offers the possibility to sync data in fixed intervals (e.g. once per hour)
In order to prevent service downtime due to critical amount of requests, call-rate limiting is applied on Web-API endpoints (for detailed information refer to API definitions)
For security reasons, a webhook endpoint passed via Connect Device / Update Webhook request must be specified with HTTPS scheme, e.g.
```
https://valid-api-endpoint.some-domain.com
```

Event-API

The Event-API enables an API consumer to be notified about important events emitted from devices (e.g. device state changes, errors). Therefore, an API consumer has to register a webhook for a connected device where supported events will be routed to.

Providing a webhook is mandatory when a device is connected via Web-API (Connect Device), and a created webhook can be updated anytime with the respective request (Update Webhook).

In order to be able to receive events, the respective endpoints have to be implemented according to definition and served by the specified webhook URL, e.g.

webhook URL: https://valid-api-endpoint.some-domain.com -> has to be submitted by API consumer

endpoint path: /devices/<device-id>/error -> has to be implemented by API consumer and hosted by webhook URL

Authentication

Authentication of event requests sent to a webhook hosted by an API consumer can be ensured with implementing client certificate validation. The used certificate is signed by GlobalSign CA, thus, for successful certificate validation the CA's root/intermediate certificates have to be trusted by the API consumer:

R3 GlobalSign Root Certificate: see GlobalSign Root Certificates
OrganizationSSL SHA-256 R3 Intermediate Certificate: see GlobalSign Intermediate Certificates

The client certificate is presented during event requests with

CN=event-api-test-internal.iodent.com

as part of the subject. For authentication, the presented certificate's subject needs to be validated against the CN (see example below).

Limitations

It is not supported for Event-API consumers to submit a webhook endpoint which is secured by any other access control like Basic Authentication, API-key, etc.

Client certificate validation - ASP.NET example

In Program.cs, implement

using Microsoft.AspNetCore.Authentication.Certificate;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(CertificateAuthenticationDefaults.AuthenticationScheme) 
  .AddCertificate(options => 
  { 
    options.Events = new CertificateAuthenticationEvents 
    { 
      OnCertificateValidated = context => 
      {
        if (context.ClientCertificate.Subject.Contains("CN=event-api-test-internal.iodent.com")) // explicitly check for the correct CN
        {
          context.Success();
        }
        else
        {
          context.Fail("Client certificate invalid!");
        }

        return Task.CompletedTask; 
      }
    };
  });

var app = builder.Build();
app.UseAuthentication();