Get iframe URL

Iframe allows to embed Improvado’s mechanism of creating datasource and destination connections in a safe way (including credentials passing). Datasources and destinations have different connection flows and attributes, Improvado handles this and has embedded all supported flows into iframe. In order to create a new connection within Improvado; call Get iframe url API, embed the iframe into your website so your customers can sign in to a datasource or setup destination connection parameters. After that you will be able to extract and load data using created connections.

Account selection

By default the iframe creates the connection as soon as the user authorizes, and that connection syncs every account the credentials give access to.

Append show_account_selection=True to the returned URL to split the flow into two steps instead:

1. Authorization — the user signs in to the data source. No connection is created yet.
2. Account selection — the accounts reachable with those credentials are listed, and the user either syncs all of them or picks specific ones. The connection is created from that choice.

The ConnectionCreated message is posted to the parent window only after the second step, so the connection always exists by the time your page is notified.

Add the parameter yourself — this endpoint does not emit it:

https://embedded.improvado.io/api/v3/iframe/?code=<str>&type=datasource&name=jira&show_account_selection=True

Not every data source can list accounts before the connection exists. Where it cannot, the iframe falls back to the default single-step flow and the parameter has no effect.

Authentication method

Some data sources offer more than one way to authenticate, for example OAuth through Improvado's app and OAuth through your own app ("Bring Your Own App"). When a data source has several methods, the iframe shows a chooser above the authorization form, with the data source's default method preselected. Each method has its own form fields and OAuth flow.

Append use_default_auth=True to the returned URL to hide the chooser and always use the default method:

https://embedded.improvado.io/api/v3/iframe/?code=<str>&type=datasource&name=spotify_ads&use_default_auth=True

Data sources with a single method never show the chooser, with or without the parameter.

Connector setup guide

Append show_setup_guide=True to the returned iframe URL to display the data source's setup instructions alongside the authorization form:

https://embedded.improvado.io/api/v3/iframe/?code=<str>&type=datasource&name=facebook&show_setup_guide=True

This is an iframe URL parameter, not a parameter of this API endpoint. Add it to the returned URL yourself; do not send it in the request body or query string of POST /api/v3/get_iframe_url.

• The guide is hidden by default. Only the exact value True enables it; omitting the parameter or using False keeps it hidden.
• On wide iframes, the guide appears to the right of the authorization form. Users can drag the divider to resize the panels or collapse the guide.
• On narrow iframes, the guide starts hidden behind a DOCS button on the right edge. The button opens the guide at full width; closing it returns to the form with entered values preserved.
• The guide uses the first documentation link returned in extra_information.documentation_links by the data source detail API. If the data source has no documentation link, the guide and DOCS button are not displayed.

This option applies to data source connections (type=datasource).