Get an API token for a web or desktop application

This page shows how an external web or desktop application obtains a user's eLabNext API token, so it can call the API as that user. The user consents once in eLabNext, and your application receives a long-lived token in return — they never generate or paste one by hand. (In eLabNext this is the "Authentication flow for 3rd party systems" option.)

Is this the right flow?

• Building a web or desktop app that acts for eLabNext users → yes, use this page.
• Just need a token for your own scripts or testing → generate one under Apps & Connections (see the REST API overview).
• Need scoped, short-lived OAuth 2.1 tokens (for example, for MCP) → see the OAuth 2.1 developer guide.

The flow has two variants — one for web applications and one for desktop applications — both covered below.

Authentication flow for web applications

Here are the prerequisites for using this authentication mechanism:

• Inside your web-based platform, redirect the user to the URL https://<your-endpoint>/members/fn/externalAuth/?rootVar=MyExampleRootVar&state=myOptionalStateString, where <your-endpoint> is the user's eLabNext environment host (for example, www.elabjournal.com).
• You need an active Add-on enabled for the user that includes a static variable authReturnURL inside your namespace. This variable needs to include the full URL to an endpoint at your web-based platform that is able to receive a so-called 'request token'.

Below is a diagram of how the exchange of tokens takes place.

The example code requires Node.js to be installed on your system. Use the following code snippets:

The steps:

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 which endpoint this API token should be requested from. This ensures that organizations that host eLabNext under their own domain name can use this feature.

This may need some explanation for end-users to understand what is asked of them. Ideally, you would validate, parse, and correct their input to end up with the proper syntax. (For example, when an end-user copies a page they regularly access, such as https://www.elabjournal.com/members/, you may want to accept and correct that input to reflect the true endpoint — www.elabjournal.com — before redirecting to https://<your-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 is echoed back to you. Use it to pass a state value, or to increase security through a mechanism on your end that prevents replay attacks or parameter manipulation (for example, by passing a salted hash of a known state).

Receive the request token

The user is redirected by you to https://<your-endpoint>/members/fn/externalAuth/?rootVar=MyExampleRootVar&state=myOptionalStateString to give consent. When accepted, eLabNext redirects the user back to you based on the authReturnURL static variable inside your Add-on namespace. This whitelists the return URL on our end for security purposes.

This also works while side-loading your script during development. In that case, the authentication flow defaults into 'Development Mode', which reads the authReturnURL only from your side-loaded script, bypassing any locally installed add-ons.

Exchange the request token for an API token

The authReturnURL is called with the request token as a URL parameter. The request token must be used within 60 seconds and can only be used once. On your end, call https://<your-endpoint>/api/v1/auth/user/exchangeToken (documented here) to exchange the request token for a long-lived API token. Post the value as Content-Type: application/json.

Authentication flow for desktop applications

The authentication flow is very similar to web applications.

The prerequisites for using this authentication mechanism are:

• Register a custom, unique URI scheme for your desktop program, so that it opens when called from a browser and accepts its parameters.
• Ideally, you call your own desktop program from inside an Add-on, so that you can pass the location.host JavaScript variable, which lets your desktop program know which eLabNext endpoint to use. If the application runs completely stand-alone, prompt the user for the endpoint, as it may differ depending on region and type of installation.
• Redirect the user to the URL https://<your-endpoint>/members/fn/externalAuth/?rootUri=MyCustomUri&source=descriptionOfMyProgram.
• After the user accepts, a redirect occurs to {{Your custom URI Scheme}}:requestToken={{requestToken}}host={{originating Host}}.

The request token received by your desktop application must be used within 60 seconds and can only be used once. On your end, call https://<your-endpoint>/api/v1/auth/user/exchangeToken (documented here) to exchange the request token for a long-lived API token. Post the value as Content-Type: application/json.