Watch this video for a comprehensive walkthrough.
Step 1: Embed the Albato iFrame in your app
Action: Add the iFrame tag provided by Albato to your application code.
Note: To authorize your user on the iFrame, Albato uses cookies that are seen as third-party cookies by the partner's domain. Since many browsers block third-party cookies, we suggest setting up a proxy for the iFrame address through the partner’s (your) domain. For instance, if your domain is partner.com and the Albato iFrame is on partner-name.albato.net, create a proxy domain, e.g., integrations.partner.com, that will proxy to partner-name.albato.net.
Guide to Setting Up a Proxy Domain for Embedded Partners
To integrate the Embedded Partner domain and the iFrame URL seamlessly, follow these steps to configure a proxy domain:
1. Check the Configuration
Embedded Partner Domain:
app.partner.ioiFrame URL:
partner.albato-embedded.netProxy Domain: Create a custom subdomain, e.g., integrations.partner.io, to proxy traffic to the iFrame.
2. Create a Proxy Domain
Set up a new subdomain (e.g.,
integrations.partner.io) in your domain registrar or DNS provider.This subdomain will act as the entry point for the iFrame traffic.
3. Configure a Reverse Proxy
Use a reverse proxy tool, such as NGINX, Apache, or Cloudflare.
For example, an NGINX configuration could look like this:
Step 2: Add the “Create a User” method to your app
You will call this endpoint whenever your user clicks to access the section of your platform where you want to show the Albato iFrame.
Action: Call the Albato endpoint to add a new user.
Inputs:
user_id* (your internal customer ID), time zone, and language.
* You can decide which user_id to pass to Albato. It could be your customer’s internal ID, organization ID, workspace ID, or any other identifier, depending on how you want to match your customers to integration users in Albato.
Outcome 1:
If Albato responds with
200, it means the user didn’t exist and has been successfully created. Albato will also return a unique session token for the new user, which will be used to display the iFrame.Action: Save the user-session-token from the response.
Use this token to pass the user’s credential data to Albato using the SSO method described in step 3 (if you haven’t already).
Next: Proceed to Step 3 to pass the user’s credential data .
Outcome 2:
If Albato responds with
400, it means the user already exists in Albato.Action: Call the “Refresh User Token” endpoint to get a new session token for the existing user. Skip the SSO method step.
Next: Go to Step 2 to retrieve the session token.
In the example below, a user (your customer) clicks on the “Automate” section where Albato integrations are placed. Upon the user’s click, you would need to execute the above API methods within your application—create a user, get a session token, and use it to display the iFrame.
Step 3: Authenticate your users on your app under the hood
If you want to seamlessly authenticate your customers on your app, you can pass the user’s credentials (API key, token, login/password, etc.) to the Albato endpoint. We recommend that you always do that for a better UX. This way your customers won’t need to insert their API credentials to connect to your app when setting up the Albato integrations.
Action: Call the Albato endpoint to set up an SSO connection.
Inputs: Call the Albato endpoint to get the connection metadata.
Without using the SSO method, your customers will need to manually create a connection to your app before they can run the integration, which might create some additional friction.
Additional Resources
This guide simplifies your integration process. Let us know if you need further clarification!