Embedded iPaaSUnified API

Headless Mode

Learn how to use headless mode in Alloy Embedded

Suggest Edits

Overview

If your product requirements insist on using your own interface at all times, look no further than Alloy Embedded's Headless Mode. Headless Mode makes it fast and easy to completely own the end to end user interface experience without displaying any Alloy-branded components (i.e. the Alloy Modal, etc).

Custom OAuth

To get started with headless mode, you must first enable Custom OAuth for all OAuth-enabled Third Party Apps (3PA). If the 3PA you're looking to integrate with does not use OAuth, feel free to skip this section.

With Custom OAuth, your end users will see your branding when they connect their integration. Read this tutorial to get started with Custom OAuth and return here when you're done.

Programmatic Credential Creation

Typically, credentials are handled via the Alloy Modal. But if you're looking to leverage a truly headless experience, you'll need to ditch the modal completely. This is where our programmatic credential endpoints come in.

List Apps

First things first, determine what type of credential you're looking to create – we have separate APIs for OAuth and non OAuth credentials.

Invoke the GET List Apps endpoint as seen below:

Sample Request

curl --request GET \
     --url https://embedded.runalloy.com/2024-03/metadata/apps \
     --header 'Authorization: YOUR_BEARER_KEY' \
     --header 'accept: application/json'

Sample Response

The data below shows a partial response for two integrations (NetSuite and Quickbooks).

{
  "data": [
    {
      "name": "netsuite",
      "icon": "https://cdn.runalloy.com/icons/netsuite.png",
      "oauth":false,
      "type": [
        "action"
      ]
    },
    {
      "name": "quickbooks",
      "icon": "https://cdn.runalloy.com/icons/quickbooks.png",
      "oauth": true,
      "type": [
        "action"
      ]
    }
    [...]
  ]
}

Credential Metadata

Next, use the GET Credential Metadata API to return relevant metadata about a credential.

Sample Request

curl --request GET \
     --url 'https://embedded.runalloy.com/2024-03/metadata/credentials' \
     --header 'Authorization: bearer YOUR_API_KEY' \
     --header 'accept: application/json'

Sample Response

This endpoint returns metadata relevant to each app. We've included a snippet for NetSuite and Quickbooks below.

Please note:

  • The isOauth key indicates if the app in question supports OAuth or not. This is especially important because we support two distinct endpoints for both OAuth and non OAuth credentials.
  • The properties array returns any relevant metadata you will need to supply when programmatically creating the credential. In the case of Netsuite, you will need to provide the realm, consumerKey, consumerSecret, tokenId, and tokenSecrets.
{
  "data": [

    {
      "name": "netsuite",
      "icon": "netsuite.png",
      "isOauth": false,
      "properties": [
        {
          "name": "realm",
          "displayName": "Realm",
          "description": "Your NetSuite realm"
        },
        {
          "name": "consumerKey",
          "displayName": "Consumer Key",
          "description": "Your NetSuite consumer key"
        },
        {
          "name": "consumerSecret",
          "displayName": "Consumer Secret",
          "description": "Your NetSuite consumer secret key"
        },
        {
          "name": "tokenId",
          "displayName": "Token Id",
          "description": "Your NetSuite token Id"
        },
        {
          "name": "tokenSecret",
          "displayName": "Token Secret",
          "description": "Your NetSuite token secret"
        }
      ]
    },
    {
      "name": "quickbooks",
      "icon": "quickbooks.png",
      "isOauth": true,
      "properties": []
    },
    {...}
  ]
}

Create a non-OAuth credential

To create a non-OAuth credential, as in the case of NetSuite, use the POST Create API Key Credential endpoint as seen below:

Sample Request

curl --location 'https://embedded.runalloy.com/2024-03/headless/credentials' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "userId":"YOUR_USER_ID",
    "credential":{
        "type":"netsuite",
        "data":{
            "realm":"123",
            "consumerKey": "4567",
            "consumerSecret": "6789",
            "tokenId": "0000",
            "tokenSecret": "11111"
        }
    }
}'

Sample Response

This endpoint returns a credentialId as seen below.

{
    "success": true,
    "credentialId": "65b6fd48e4142dd86c387f5e"
}

Create an OAuth credential

To create a OAuth credential, as in the case of NetSuite, use the POST Create OAuth Credential endpoint as seen below:

Sample Request

curl --location 'https://embedded.runalloy.com/2023-12/headless/oauthUrl?userId=YOUR_USER_ID&app=quickbooks' \
--header 'Authorization: Bearer YOUR_API_KEY'

Sample Response

This endpoint returns a redirectUrl for you to redirect your end users to in order to complete the OAuth flow.

{
    "data": {
        "redirectUrl": "https://api.runalloy.com/api/strategy/quickbooks/authorize?userId=YOUR_USER_ID"
    }
}

With that, you've created your first credential.

User-defined Data Mappings

Some integrations may require end users to map values to the 3PA as seen in this article.

Let's assume you need your end user to provide their own value for "Customer's Email" as seen below. To allow them to provide their own value(s), select the Configurable by user checkbox as seen below.

Typically, the end user will provide their own data mappings for the "Customer's Email" within the Alloy Modal. However, if you want a truly headless experience, you'll need to leverage the POST Start Headless Installation endpoint.

Sample Request

This endpoint takes a userId, an array of credentialIds, and the integrationId of the integration to render headlessly.

curl --location 'https://embedded.runalloy.com/2024-03/headless/startInstallation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "userId":"YOUR_USER_ID",
    "credentialIds":["YOUR_CREDENTIAL_ID"],
    "integrationId":"YOUR_INTEGRATION_ID"
}'

Sample Response

This endpoint creates an installation which can be referenced by its installationId. The fields array returns the relevant fields you'll want to display to your end user along with the associated data type.

{
    "data": [
        {
            "workflowId": "65b7005ae9761102a64ddd3b",
            "app": "netsuite",
            "blockId": "3a8a8e50-f0e5-488b-9b7b-53656e93d392",
            "fields": [
                {
                    "name": "customerEmail",
                    "displayName": "Customer's Email",
                    "type": "string",
                    "required": true
                }
            ]
        }
    ],
    "installationId": "65b701c2f5ba66db3bc53a68"
}

Completing the Installation

Now that you've created the installation and used the POST Start Headless Installation endpoint to return the metadata needed for your end user to map their data, you'll want to actually pass that data back to Alloy Embedded.

To do so, invoke the GET Complete Headless Installation endpoint as seen below:

Sample Request

curl --location 'https://embedded.runalloy.com/2024-03/headless/completeInstallation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
  "installationId": "YOUR_INSTALLATION_ID",
  "data": [
    {
      "workflowId": "YOUR_WORKFLOW_ID",
      "blockId": "YOUR_BLOCK_ID",
      "fields": [
        { "name": "customerEmail", "value": "[email protected]" }
      ]
    }
  ]
}
'

Sample Response

Assuming you passed in valid information, you will see a success message and associated 200 OK status as seen below.

{
    "message": "Installation completed successfully"
}

Wrapping Up

In this article, we took a look at how to use Alloy Embedded's fully headless mode to provide a completely whitelabeled end user experience. Using Headless Mode, your end users will never even know you're using Alloy Embedded to power integrations!

Updated 3 months ago