Receiving an API key

To receive an API key from an eLabNext user for use within your own web-based platform, it is best to use the eLabNext ‘Authentication flow for 3rd party systems’ option.

Authflow eLabNext

Here are the prerequisites for using this authentication mechanism:

  • Inside your web-based platform, you will need to redirect the user to the URL https://{{eLab Endpoint}/members/fn/externalAuth/?rootVar=MyExampleRootVar&state=myOptionalStateString
  • You will need to have an active Add-On for the user enabled which includes a static variable authReturnURL inside your namespace.
    • This variable needs to include the full URL to and endpoint at your web-based platform that is able to receive a so-called ‘request token‘.

Authentication Flow Explained

Below is a diagram how the exchange of tokens takes place. Download the example code to see it in action. The example code requires nodeJS to be installed onto your system.

API Exchange Authentication Flow Diagram

The steps:

  1. User initiates request for API token

    At your platform, there will be an action for the end-user to request an API token from eLabNext. The only prompt to the end-user is to which endpoint this API token would need to be requested. This ensures that organizations that host eLabNext, under their own domainname, will be able to use this feature.

    This may need some explanation for end-users to understand what is asked of them. Ideally, you would validate/parse & correct their input to end up with the proper syntax. (E.g. when an end-user would copy/paste any page that they regularly access, such as https://www.elabjournal.com/members/, you may want to accept and correct that input to reflect the true ‘endpoint’ which is www.elabjournal.com before redirecting it to https://{{eLab Endpoint}/members/fn/externalAuth/?rootVar=MyExampleRootVar&state=myOptionalStateString).

    Here, rootVar needs to be the rootVar of your Add-On. state is an optional parameter that will be echoed back to you. This may be used to pass over some state value, and/or to increase security by any mechanism implemented on your end that prevents replay-attacks or parameter manipulation (e.g. by passing over a salted hash from a known state).

  2. Receives ‘Request Token’

    The user now gets redirected by you to https://{{eLab Endpoint}/members/fn/externalAuth/?rootVar=MyExampleRootVar&state=myOptionalStateString in order to give consent. When accepted, eLabNext will redirect the user back to you based on the static variable authReturnURL inside your Add-On namespace. This whitelists the return URL on our end for security purposes.

    Please note that this also works while sideloading your script during development. In that case, the authentication flow will default into ‘Development Mode’, which means it will only read the authReturnURL from your side-loaded script, bypassing any locally installed add-ons.

  3. Exchange ‘Request Token’ with API token

    The authReturnURL is called, containing the request token as an URL parameter. The request token needs to be used within 60 seconds and can only be used once. On your end, you will then reach out to the API call https://{eLab Endpoint}/api/v1/auth/user/exchangeToken
    (documented here), to use the request token for receiving a long-living API token.

    Download the example code to see it in action. The example code requires nodeJS to be installed onto your system.

Get started with eLabNext today

Personal demo, free lab workflow assessment, and friendly expert guidance.