Authentication

Calls to the Lean API endpoints in production use certificates and mTLS to authenticate requests. You can revoke certificates and download replacements from your Application Dashboard.

Your API certificates carry many privileges, so be sure to keep them secure! Do not share your certificates in publicly accessible areas such as GitHub, client-side code, and so forth.

To use your API certificates, set up a truststore and a keystore for use with an SSL context in your server side requests.

API requests without proper authentication will fail.

Guide to setting up mTLS →

Setting up Mutual TLS (mTLS)

Calls from your backend to Lean are required to be made over mTLS. If you'd like to learn more about what mTLS does and how it works you can learn more here.

Getting Your Certificates

When you create an application at dev.leantech.me you will be able to download two files from the Integration section of the developer portal. By clicking 'generate new certificate' a zip folder containing my_app_private_key.pem file and a my_app_cert.crt file will be downloaded.

Within the UI on dev.leantech.me you should also download the Lean certificate chain. To do this click the button labelled 'Certificate chain'. This should trigger a further download of a zipped folder containing lean_public_cert_chain.pem.

With the above complete you should now have three files.

Setting Up Your Keystore

The below is tailored to setting up a Java environment, but most of the steps are similar regardless of technology.

Create a truststore using the lean_public_cert_chain.pem file downloaded from the developer portal.

bash

keytool -import -trustcacerts -keystore [yourApp]-trustStore.jks -storepass [yourApp]TruststorePassword -alias Root -file lean_public_cert_chain.pem

Next create a keystore using the private key and app certificate, you will be prompted to enter a password, e.g. myAppKeystorePassword

bash

openssl pkcs12 -export -out myApp-keyStore.p12 -inkey my_app_private_key.pem -certfile certs/ca.pem -in my_app_cert.crt

Add the truststore and keystore into a location that can be accessed by your application such as in the src/main/resources folder.

Finally use the truststore and keystore to create an SSLContext and inject this into your rest client.

java

// RestTemplate client example

SSLContext sslContext =
        SSLContextBuilder.create()
                .loadKeyMaterial(keyStoreUrl, keyStorePassword.toCharArray(), privateKeyPassword.toCharArray())
                .loadTrustMaterial(trustStoreUrl, trustStorePassword.toCharArray())
                .setProtocol("TLSv1.3")
                .build();
HttpClient httpClient = HttpClientBuilder.create().setSSLContext(sslContext).build();
ClientHttpRequestFactory clientHttpRequestFactory = new HttpComponentsClientHttpRequestFactory(httpClient);
restTemplate.setRequestFactory(clientHttpRequestFactory);

java

// WebClient client example

SSLContext sslContext =
        SSLContextBuilder.create()
                .loadKeyMaterial(keyStoreUrl, keyStorePassword.toCharArray(), privateKeyPassword.toCharArray())
                .loadTrustMaterial(trustStoreUrl, trustStorePassword.toCharArray())
                .setProtocol("TLSv1.3")
                .build();

HttpClient httpClient = HttpClient.create().secure(sslSpec -> sslSpec.sslContext(sslContext));

WebClient webClient = WebClient.builder()
    .clientConnector(new ReactorClientHttpConnector(httpClient))
    .build();