--- title: "Get iframe URL" method: POST path: "/api/v3/get_iframe_url" tags: ["iframe"] --- # Get iframe URL `POST /api/v3/get_iframe_url` ## Request - Base URL: `https://embedded.improvado.io` - URL: `https://embedded.improvado.io/api/v3/get_iframe_url` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) 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=&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=&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: ```text https://embedded.improvado.io/api/v3/iframe/?code=&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`). ## Query parameters - `show_connectors_list` boolean - `show_datasources` boolean - `show_accounts` boolean - `show_accounts_only_on_auth` boolean - `use_default_auth` boolean ## Request body - object - `workspace_id` integer: Workspace ID - `type` string: defines whether you want to create a destination connection or datasource connection. Allowed values are destination or datasource (optional parameter) - `name` string: string identifier of datasource or destination you want to connect to (optional parameter) ## Response `200` Get iframe URL - object - `url` string: iframe URL ## Other responses - `400`: Bad Request - `401`: Forbidden --- [API](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3.md) - [All operations](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/revisions/a881099bd6c4?raw)