Managed authentication

We securely store third-party Provider credentials, unify your authentication interface, and maintain credentials (e.g. refresh tokens) on your behalf. There are two ways to allow your customers to authenticate with third-party providers:

1. Embed it into your application (Embedded authentication)
2. Redirect your customers to Supaglue-hosted authentication pages (Supaglue-hosted authentication)

Embeddable authentication

We support three kinds of authentication methods for your customers to authenticate with third-party providers:

1. OAuth 2.0
2. API key
3. Access key

Your authentication method depends on the third-party provider you want to connect to. For example, Salesforce requires Oauth 2.0 authentication, while Apollo requires API key authentication.

OAuth 2.0 (oauth2)

Supaglue supports 3rd-party providers that use OAuth 2.0 for authentication.

Supaglue supports third-party providers that use OAuth 2.0 Authorization Code Flow (aka Authorization Code Grant). This means that your customers will be redirected to the third-party provider's login page to authenticate themselves. Once authenticated, the third-party provider will redirect your customer to Supaglue with an authorization code. Supaglue will then exchange the authorization code for an access token and refresh token.

Create a Connection

An Embedded Link is a single Supaglue URL (with customer-specific query parameters) that initiates the Authorization Code Flow.

You can expose an Embedded Link in your application as a link or button so your customers can initiate an authentication flow with their third-party provider, e.g. Salesforce, or simply pass them along to customers via email or chat.

Embedded Link

An Embedded Link has the following format:

https://api.supaglue.io/oauth/connect?applicationId={APPLICATION_ID}&customerId={CUSTOMER_ID}&providerName={PROVIDER_NAME}&returnUrl={RETURN_URL}

Query parameters:

Parameter	Description	Required
applicationId	The unique identifier for your Supaglue application	Yes
customerId	The unique identifier for a customer in your application	Yes
providerName	The name of the third-party provider (e.g. salesforce, hubspot, ...)	Yes
returnUrl	The URL to return to once the OAuth connection is complete. NOTE: this should be uriEncoded	Yes
loginUrl	The Oauth2 hostname for authorize and token endpoints. Use this for Salesforce sandbox accounts. The value should be https://test.salesforce.com for that use case. NOTE: this should be uriEncoded	No
scope	Required for Microsoft Dynamics 365 connections. This based on the customer's Dynamics 365 URL and should be in the form <customer dynamics URL>.default e.g.scope=https://org8d6f84ed.crm.dynamics.com/.default. NOTE: this should be uriEncoded	No
autoStartOnConnection	Whether to start syncs for objects defined in your SyncConfig upon a successful oauth connection. This query parameter overrides auto_start_on_connection set in your SyncConfig.	No

API key (api_key)

Supaglue supports third-party providers that use API keys for authentication. API keys range widely in their format and behavior. At a high level, your customers generate an API key in their third-party provider account, e.g. Apollo, and you pass this on to Supaglue.

Create a Connection

Use Supaglue's Management API, the Create Connection API, to save customers' third-party provider API keys. Unlike Embedded Links, this cannot be initiated in your client application but from your backend server.

info

Since the API above is a cross-original POST request, you must proxy the call through your backend server.

Access keys (access_key_secret)

Supaglue supports third-party providers that use access keys for authentication. Access keys are similar to API keys but consist of two parts: an ID and secret.

Create a Connection

Use Supaglue's Management API, the Create Connection API, to save customers' third-party provider access keys. Unlike Embedded Links, this cannot be initiated in your client application but from your backend server.

info

Since the API above is a cross-original POST request, you must proxy the call through your backend server.

Supaglue-hosted authentication

We offer Supaglue-hosted authentication pages for your customers to authenticate with their third-party provider. You can redirect customers to them using Magic Links.

Magic Link

Supaglue's Magic Link is a shareable URL that allows your customers to create a connection to your application without having to write any frontend code.

https://app.supaglue.io/links/bec0250e-6b50-4853-a785-c133232dacfa

Generating a Magic Link

A Magic Link can be created in one of two ways:

• From the Supaglue Management UI
• Programatically via Management API

Management UI

You can create a Magic Link by:

1. Navigating to the Customers page

2. Finding the customer you want to create the Magic Link for, and clicking on the Magic Link column

3. Filling out the relevant information, including provider, return url, and expiration.

https://app.supaglue.io/application/62605dc1-148e-4c53-a850-82e10f71ed23/customers

Management API

Supaglue also offers the ability to create Magic Links via our Management API.

You can do so by making a POST request to the /magic_links endpoint. You will have to specify the:

Supaglue Cloud

curl --location 'https://api.supaglue.io/mgmt/v2/magic_links' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{API_KEY}}' \
--data '{
    "customer_id": "{{CUSTOMER_ID}}",
    "provider_name": "{{PROVIDER_NAME}}",
    "return_url": "{{RETURN_URL}}",
    "expiration_secs": {{EXPIRATION_SECS}}
}'

Localhost

curl --location 'http://localhost:8080/mgmt/v2/magic_links' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{API_KEY}}' \
--data '{
    "customer_id": "{{CUSTOMER_ID}}",
    "provider_name": "{{PROVIDER_NAME}}",
    "return_url": "{{RETURN_URL}}",
    "expiration_secs": {{EXPIRATION_SECS}}
}'

• API_KEY: Your Supaglue API key as generated from the API Key tab
• CUSTOMER_ID: 1234 (your customer's unique identifier)
• PROVIDER_NAME: e.g. hubspot or salesforce
• RETURN_URL: URL to redirect to after the connection is authorized
• EXPIRATION_SECS: The number of seconds after which the magic link will expire and become invalid.

Consuming the Magic Link

Once your customer navigates to the Magic Link, they will have the opportunity to go through the Authentication flow for that provider. In many cases, this will be identical to the standard OAuth flow as documented in Embedded Links.

For some providers, customers will have to provide additional information to complete the authentication flow, e.g.:

• the Instance URL (for Microsoft Dynamics 365)
• the API Key (for Apollo, which does not support OAuth)
• whether to connect to Sandbox or Production environment (for Salesforce)
• etc.

info

A Magic Link can only be consumed once, after which the Magic Link will be considered invalid.