Additional features
      Back to home
      1. Help Center
      2. Ecochain Helix
      3. Additional features

      API

      All you need to know to connect with the Helix API to query product impact information.

      Summary

      An API is available which can be used to query the results of the impact analysis. This API provides impact information on all products in the account. The API gives the following data:

      • Indicators of calculation method selected
      • Includes the Production phase A1-A3
      • Also company and product meta data is provided

      Currently not included:

      • Bill of Materials
      • Energy use 
      • Use and EOL scenario’s (A4-D)
      • Transport values (only the total impact, not the contributors)

      The API is provided in Beta and still under development.

      Documentation

      The API schema and documentation are available as a Swagger template here. And a Postman demo environment is available here.

      The documentation above includes example queries that can be executed against a real environment with a predefined setup.
      So you don't even have to follow the steps below if you just quickly want to play around with the API.

      Below is a schematic representation of the components in the API, and how to use the links to navigate between them:

       

       

      The green circles represent resources, which can contain links to other resources.
      When they are stacked, it means an array of such resources can be returned.

      When the relationship arrow points to the top of a stack, or just to a single resource, it means that link will return a single resource.
      When the relationship arrow points to the bottom of a stack, it means that the link will return an array of resources.

      The main entrypoint is the search query (/products), which returns an array of Product resources.
      Another useful entrypoint is the impact definitions query (/impactdefinitions), which returns all the impact definitions available to you.

      Product

      A product calculated by Company, containing Impacts and linked to Scenarios

      LINKS

      Link Rel
      Description
      self Self link
      impacts Link to the definition of this impact

      Company

      The Company owning the Products

      LINKS

      Link Rel
      Description
      self Self link
      products Link to list Products for this Company

      Scenario

      A usage or end-of-life Scenario linked to Products

      LINKS

      Link Rel
      Description
      self Self link
      impacts Link to list of Impacts for this Scenario
      products Link to list of Products connected to this Scenario

      Impact

      The calculated impact against a midpoint or endpoint.
      The list of impacts returned depends on the 'LCA Standard' setting in your EcoChain account.

      LINKS

      Link Rel
      Description
      self Self link
      impactDefinition Link to list of Impacts for this Product
      scenarios Link to list of Scenarios connected to this Product
      company Link to the Company owning this Product

      LIST RESULT LINKS

      Link Rel
      Description
      product Link to Product to which these Impacts belong
      scenario Link to Scenario to which these Impacts belong

      Impact Definition

      Impacts are given as id-value pairs in the API.
      In the table below you'll find their english names, units and to which LCA Standard and presentation they belong to.

      The impact definitions here are also available through the impactdefinitions endpoint, but in the API you'll only see impact definitions corresponding to the LCA standard configured for your EcoChain account.

      Getting access

      To use this API with real data, you'll first need to create an API key and secret.

      Under Settings, and Company Information, you'll find a section for Client API Keys.
      Click on the Generate Key/Secret button to create a new keypair.

      You'll see a new Public Key and Private Secret appear.
      Copy the secret to a safe place.


      Note: It's important to understand that the secret is like a password, and should never be included in any sourcecode or shared with anyone!

      The next time you view the page, you won't be able to see the secret.
      You can however regenerate it if you lost it.

      Click on the description, and start typing to enter a description for the keypair.

       

      Usage

      To use the API, you'll first need to exchange your Public Key and Private Secret for an access token.
      This access token is valid for a short time. Each time it becomes invalid, you'll need to follow this authentication step to get a valid access token again.

      Authentication

      There are two ways to authenticate.
      You could include your credentials in:

      • Request body with user ID, or
      • Basic Auth header

      Request body with user ID

      1. Authenticate by using "GET authenticate client and user (form)"

      In order to connect using curl, you would need to authenticate using the company's key and secret and include the user ID.

      curl -H "Content-Type: application/x-www-form-urlencoded"
      -d "grant_type=client_credentials&client_id={KEY}&client_secret={SECRET}"
      -v
      https://helix.ecochain.com/api/v1/authenticate/clientip/127.0.0.1/user/{USER_ID}

      The {KEY} and {SECRET} can be found at the bottom of the Company information page.

      The {USER_ID} can be found on the page Users in settings. Click on User permission of given user and you can find the user ID in the URL. 

      E.g. using curl:

      curl
      -H "Content-Type: application/x-www-form-urlencoded"
      -d "grant_type=client_credentials&client_id=KEY_34F69848D30E2396FD346BE8123DBE23F02C08FFBB15F3394294FA5D508A06BA&client_secret=secret_13812685c217427ebd8b54b5a9f84cc2a667bbc2"
      -v
      https://helix.ecochain.com/api/v1/authenticate/clientip/127.0.0.1/user/72d44acb-a76f-421c-b7se-f1907c56e37f

      2. Get info by using POST requests

      As a response, you would get similar results like this. Do note that the bearer token string is long and it is cut down in the example below.

      Response

      "access_token":"ZXl.....Q28=","token_type":"Bearer"

       

      Use bearer token

      Use this bearer token (i.e. ZXl.....Q28=) in all GET and POST requests

      For example:

      curl -H "Authorization Bearer BEARER_TOKEN" https://app.ecochain.com/api/v1/users/me

       

      curl -H "Authorization: Bearer ZXlK.......Q28=" https://app.ecochain.com/api/v1/products

       

      Basic Auth

      E.g. using curl:

      curl -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials" -u KEY_34F69848D30E3296FD346BE8F53DBE23F02C08FFBB15F3394294FA5D508A06BA:secret_13808685c217427ebd8b54b5a9f84cc2a667bbc2 -v  https://app.ecochain.com/api/v1/authenticate

      Token Response

      With both methods above, the access token will be returned as JSON:

      {
          "access_token": "ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6STFOaUlzSW1wMGFTSTZJbVJoTkRSaU5EWTRMVGRsWTJFdE5EWmlaUzA0TVRjMkxURTBZV0k0TnpaalpqUXlOaUo5LmV5SnBjM01pT2lKbFkyOWphR0ZwYmk1amIyMGlMQ0pxZEdraU9pSmtZVFEwWWpRMk9DMDNaV05oTFRRMlltVXRPREUzTmkweE5HRmlPRGMyWTJZME1qWWlMQ0pwWVhRaU9qRTFNelUyTVRjeU5UUXNJbVY0Y0NJNk1UVXpOVFl5TURnMU5Dd2lkV2xrSWpvaVMwVlpYMEpFUWtRd1JqWTRNVFl5UkRReE5FTkZRMEUzT1RJd05UQXdNRUUxUVRrek1UWTRRMFpHT0RFeU9UUTJORFkzT0RsRU1rRkZORUZDUTBWRk56WTRRamNpTENKeWIyeGxjeUk2ZXlKVVdWQlBNeTVHYkc5M09rVjJaWEo1WW05a2VTSTZlMzBzSWxSWlVFOHpMa1pzYjNjNlFYVjBhR1Z1ZEdsallYUmxaRlZ6WlhJaU9udDlMQ0pGWTI5RGFHRnBiaTVRWVdOcllXZGxPbVp2YjNSd2NtbHVkQ0k2ZTMwc0lrVmpiME5vWVdsdUxsQmhZMnRoWjJVNlptOXZkSEJ5YVc1MFgzQmhhV1FpT250OWZTd2liR05oVTNSaGJtUmhjbVFpT2lJeVpqTmlZalF5TXkxbE9HTTBMV0kwWldNdFpEZzNZaTFtTnpkbE5UYzROV05oTlRraUxDSjJZV3hwWkVOdmJYQmhibWxsY3lJNld5SXlZV0ZtWVRObU1DMWtObU00TFRRM1lqSXRZVEF4WWkxa056VTFNV1F4Tm1JNE5HVWlMQ0k1TkdVek1EaGlOUzFsTmpkbUxUUXpZall0T0dKbE1DMWhZMlJrWldFMlpESmtPV1VpTENKaU5EUXlZbUptT0MweU1qRm1MVFEyTlRJdFlUSTJZUzFtTVdFeFpHVXdNRGN3TlRZaVhYMC5QSW9DX1ZjU2dmRl9KSTZBRDVEOHY2ZWNGaEJXcnI2eTZkbldMNXIwNlA4",
          "expires_in": 3600,
          "refresh_token": null,
          "token_type": "Bearer"
      }

      The access_token should then be included in every following request.

      You'll notice the empty refresh_token here. That's only used when one of the client-ip specific authentication methods are used.
      And that's mostly through internal links from the EcoChain platform.

      Searching

      We've created some Postman examples which should help you get started with using the API.

      1. First, install Postman,

      2. Then click here to open the example project with predefined queries to run them in Postman.

      3. Make sure you've got the 'production sandbox' environment selected in Postman

      The examples in Postman are configured to use a specific example account in EcoChain.
      Important: Execute one of the 'authenticate' queries before the others.

      Have fun!

      3rd party applications and SSO

      With the API, it's possible to interact with Ecochain data as a 3rd party application.

      When the link to the application is built into the Ecochain platform, it's even possible have SSO capabilities for users.

      At the time of writing, our API is not fully SSO compliant, but we solve it with a custom flow, where the user first logs into the Ecochain platform, and then opens the 3rd party application with an app specific link.

      3rd party application developers would then not expose any login capability of their own, but expect the access and refresh tokens to be passed to them in the form of a GET request.

      The following 'launch' parameters will be sent with the GET request when opening the 3rd party application:

      • access_token
      • expires_in
      • refresh_token
      • token_type

      It's then the responsibility of the 3rd party application to extract the value of the 'access_token' parameter and in all following requests to the API, pass it in as a Bearer token.

      Let's say that you have developed an app to display footprint data for any products.
      Your company is called Acme, and you'd like for Ecochain customers to use your app for displaying their products.

      Windmill Company is an Ecochain customer, and they would log into Ecochain to eventually use your app for displaying their products.

      Here's how the components work together across the different environments

       

       

      1. User is logged into Ecochain and clicks the 3rd party app launch button
        Frontend logic will open a new browser tab and send a GET request to our internal web controller
      2. Our web controller will authenticate the user against the API server and receive an access token

      3. Our web controller will send a GET request with launch parameters to the launch URL of your app
        E.g. 

        curl -X GET ‘https://acme.com/launch?access_token=ABCDEF&expires_in=3600&refresh_token=GHIJKL&token_type=Bearer

      4. Your controller will extract the 4 parameters, and use the access token to make requests to the Ecochain API

        E.g. First get the current user

        curl -H "Authorization: Bearer ABCDEF" https://app.ecochain.com/api/v1/users/me

        then get the current company

        curl -H "Authorization: Bearer ABCDEF" https://app.ecochain.com/api/v1/companies/me

        then get all products for the company

        curl -H "Authorization: Bearer ABCDEF" https://app.ecochain.com/api/v1/companies/{companyId}/products

      5. Your controller will render the page with contents fetched from the API

      As you can see, we've made SSO really simple for 3rd party application developers.
      All you need to do is expose an endpoint that can receive GET requests with the 4 launch parameters and render the user interface.