> This page is for version 2024-02-08.
> For other versions, use one of these documentation indexes:
> - 2025-09-18 (default): https://apidocs.polytomic.com/2025-09-18/llms.txt
> - 2024-02-08: https://apidocs.polytomic.com/2024-02-08/llms.txt
> - 2023-04-25: https://apidocs.polytomic.com/2023-04-25/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://apidocs.polytomic.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://apidocs.polytomic.com/_mcp/server.

Hosted authentication runs the authentication flow in a Polytomic-hosted window.
After minting a token, you navigate the user to the supplied URL. After the user
authenticates and configures their connection, Polytomic redirects back to your
app with the new connection details. To keep the flow inside your React app
instead, see [Embedded authentication](/2024-02-08/guides/connect/embedded).

![HubSpot](https://fern-image-hosting.s3.amazonaws.com/polytomic/polytomic-oauth.png)

![Snowflake](https://fern-image-hosting.s3.amazonaws.com/polytomic/polytomic-snowflake.png)

## 1. Mint a token

Mint a Connect session from your backend with
[`POST /api/connections/connect/`](/2024-02-08/api-reference/connections/connect):

```bash
curl -X POST https://app.polytomic.com/api/connections/connect/ \
  -H "Authorization: Bearer $POLYTOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Salesforce",
    "whitelist": ["salesforce"],
    "redirect_url": "https://example.com/integrations/connected"
  }'
```

| Field                   | Meaning                                                                                                                                                                                      |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                  | Required. How the connection appears in the organization. Unique per connection type.                                                                                                        |
| `redirect_url`          | Required. Where the user returns when the flow ends.                                                                                                                                         |
| `whitelist`             | Connection types to offer, such as `["salesforce"]`. One entry opens that type's form; several show a picker first. See [`GET /api/connection_types`](/2024-02-08/api-reference/connections/get-types). |
| `connection`            | ID of an existing connection to reconnect or edit.                                                                                                                                           |
| `dark`                  | Use the dark theme.                                                                                                                                                                          |
| `use_organization_name` | Show the organization's name instead of your partner name.                                                                                                                                   |
| `ttl`                   | Token lifetime in seconds. Default `300`, maximum `604800` (7 days).                                                                                                                         |

The response's `data.redirect_url` is the hosted page for this session.

> **Keep the API key on your server**
>
> Never send your API key to the browser. The browser only needs the hosted
> page's URL.

## 2. Navigate the user to the page

Open `redirect_url` in a new tab or the current window. The page can't be
embedded in an iframe.

The user will be prompted to authenticate and complete any additional
configuration required to create the desired connection.

## 3. Handle the redirect

When the flow completes, Polytomic redirects to your `redirect_url` with these
query parameters:

| Parameter    | Value                                       |
| ------------ | ------------------------------------------- |
| `connection` | The connection ID.                          |
| `name`       | The connection name.                        |
| `status`     | The connection's status, such as `healthy`. |

```text
https://example.com/integrations/connected?connection=8a1f1c3e-2a64-4c3b-9a43-6f1e0c2b7d55&name=Acme+Salesforce&status=healthy
```

If the user cancels or the session expires, `status` is `canceled`. If the user
leaves before finishing, an incomplete connection can remain in the
organization. Check a connection's `status` before using it, and delete unused
ones.

> **Verify the result on your backend**
>
> Query parameters come from the browser. Confirm the connection with [`GET
>   /api/connections/{id}`](/2024-02-08/api-reference/connections/get) before relying on
> them.

## Reconnect a connection

To reconnect or edit a connection, mint a session with `connection` set to its
ID. `name` is still required but ignored. A healthy connection opens on the
success screen; otherwise the form opens with the saved values.

## Branding

* **Logo.** Email an SVG to [support@polytomic.com](mailto:support@polytomic.com). It replaces the Polytomic
  logo in the header, with "Powered by Polytomic" in the footer.
* **Dark theme.** Set `dark: true`.
* **Name.** The page shows your partner name by default. Set
  `use_organization_name: true` to show the organization's name.

![Light mode](https://www-polytomic-assets.s3.us-west-2.amazonaws.com/api-docs/custom-logo-light-mode.png)
![Dark mode](https://www-polytomic-assets.s3.us-west-2.amazonaws.com/api-docs/custom-logo-dark-mode.png)