Embedded iPaaSUnified API

Alloy Link

Learn when and how to use Alloy's link based authentication feature.

Suggest Edits

Overview

In our Quick Start guide, we embedded the Alloy Modal into our application's frontend using the Frontend Javascript SDK. Sometimes, however, you may need a more nimble approach. In this article, we'll take a look at how Alloy Link makes installations faster and easier.

How it Works

Using our link based authentication, you can generate a secure hosted link for your end users. Simply generate this link programmatically or via the Alloy Dashboard.

Alloy Link via the Alloy Dashboard

Let's assume you want to build a quick Magento integration with just one workflow: whenever an order is created in Magento, stream that data back to your webhook ingest server.

Your workflow will probably look something like the below.

Assuming you've build and published your workflow, navigate to the Magento integrations page. Click the Share button.

Follow the below steps:

  • Share with a user: Share it with an existing user or create a new one. You can choose to generate the link for one of your existing users or create a new user. To create a new user, select share it with a new user. Input the user's email address. Note that Alloy Embedded does not send an email alerting the user that this link is created – it's your responsibility to do so. The email you enter here creates a new Alloy Embedded end user account.
  • Get your Link: Click Generate Link
  • Copy Link: Copy your link and send it to the individual you want to install the workflow! You can specify how long you want the link to last for by entering an Expiration Time. By default, Embedded Links last for 7 days (1 week) but you can specify other durations. Note that once a link is used, it becomes invalid after the integration is activated.

Viewing the Link

Once you've generated an Alloy Link, you'll see something like the following:

https://app.runalloy.com/embedded-install?integrationId=XXXXXXX&token=YYYYYYYY.ZZZZZZZZZZZZZ.WWWWWWWWWWWWWW-VVVVVVVVV&forgeMode=engaged&alwaysShowCredentials=true

Open this link in a new (incognito/private) browser window as seen below.

Alloy Link uses the same underlying technology as the Alloy Modal when rendered via the Frontend JavaScript SDK. The experience remains the same – enter your credentials and hit Finish Installation when you're done.

Alloy Link via the API

In the previous section, we looked at how to generate an Alloy Link via the Alloy Dashboard. Now, let's take a look at how to do so programmatically.

To generate a link programmatically, invoke the GET /install-url link as detailed here. This endpoint expects a userId and integrationId. You can generate a user or list all existing users via our Create a User and List all Users endpoints.

Once you've made a request to this endpoint, it'll generate the Alloy Link, similar to the above section. Note that this link must be generated on the backend because this endpoint requires your API key.

Notifying your app upon completion

If you're familiar with the our Frontend JavaScript SDK, you'll likely be aware that it returns a callback which is oftentimes used to take action (like updating an integrations page) when a user has completed authentication. With Alloy Link, no such callback exists because Alloy Link lives on Alloy's website. That being said, it's still quite useful (and oftentimes required) to know when a user has successfully installed an integration so your application can react accordingly.

To remedy this, we've created the Integration Installation Webhook which is invoked upon each successful integration install. You may supply us with a POST webhook URL where Alloy Embedded will notify you each time a user successfully installs an integration. We'll send you the following each time:

  • userId (string)
  • workflowIds (array)
  • integrationId (string)
  • success(boolean)

Additionally, each request includes an X-Alloy-Signature header to validate the validity of the incoming webhooks. You can read more about the signature and how to validate it here.

Wrapping Up

And just like that, you've set up Alloy Link. As you can see, Alloy Link makes it really easy to build integrations. Behind the scenes, Embedded link uses the same technology as Embedded SDK – when a user installs a workflow, the link generates a child workflow (aka a copy) of the parent workflow.

You can any other existing Embedded APIs in conjunction with Alloy Link. For example, you can easily leverage our logging and compliance APIs. Happy building!

Updated 4 months ago