...

For periodic data consumption a client application is required, which uses the OAuth 2.0 client credentials flow. In this flow a certificate(recommended) or a client secret is used to prove the client application’s identity. The flow works like this

1. The client application obtains an access token

   1. Each access token permits the client to consume the Heimdall API for one hour

2. The client calls the Heimdall API with the access token and renews the token when expired

The Heimdall API clients repository provides sample implementations in 3 languages. Each client implementation contains a README with instructions to get started.

• C# / .NET 57

• Java

• Python

API demo

Heimdall offers access to demo data if your organization wants to test out the capabilities of the Heimdall Cloud API. After you have been granted access, head out to Swagger demo version of the API here, or run your Heimdall API client of choice with the parameter useDeveloperApi set to false.

Certificate requirements

If your organization has a CA server(certificate authority server), it can be used to issue a signed X.509 certificate. Send the certificate to Heimdall to connect it to your client application.

If your organization does not have a CA server, you can create a self-signed certificate by following the instructions below.

1. Install openssl

2. Generate a RSA private key to sign the certificate

   openssl genrsa -out certificatePrivateKey.pem 2048

3. Create a PKCS8 version of the private key (only needed for the Java client)
   openssl pkcs8 -topk8 -inform PEM -outform DER -in certificatePrivateKey.pem -nocrypt > pkcs8PrivateKey.pem

4. Create a certificate request and fill in the requested details (leave the challenge password blank)

   openssl req -new -key certificatePrivateKey.pem -out certificateSigningRequest.csr

   Image Removed

5. Create a .crt certificate (does not contain private key) with the private key and certificate signing request

   openssl x509 -req -days 36500 -in certificateSigningRequest.csr -signkey certificatePrivateKey.pem -out certificate.crt

   1. To find the certificate thumbprint, open certificate.crt and go to Details

      Image Removed

6. Create a .pfx version of the certificate (contains the private key, but is secured with password)
   openssl pkcs12 -export -out certificate.pfx -inkey certificatePrivateKey.pem -in certificate.crt

   1. When prompted, enter a secure password for the certificate

7. Send the .crt certificate (does not contain private key) to Heimdall to connect it to your client application

The required certificate credentials required to authorize differ between the sample implementations in Java, Python and .NET.

Java

• Private key -pkcs8PrivateKey.pem

• Certificate - certificate.crt

Python

• Private key - privateKey.pem

• Certificate thumbprint (step 5a above)

.NET

...

Certificate - certificate.pfx

...

Certificate password to certificate.pfx (step 6a above)

...

Client Secret

The API clients authenticate using the Client Credentials Flow with Azure Active Directory B2C. A client id and secret must be used for authentication, and is provided by Heimdall Power on request.