Embed Portal

The embed link expires after 48 hours by default, though this may be configurable in the future. During that time, it can be shared or opened in various ways, including direct messages, email, new browser tabs, or iframes.

When a merchant redeems the embed link, the app sets a cookie-based session in the browser. This session allows the merchant to continue adjusting or completing the connection until the session expires. Each request validates the session and uses the associated API Key on the merchant’s behalf. The API Key itself is never exposed.

If the API Key is ever disclosed, it may allow unauthorized users to modify or delete integrations. Any attempt to reuse an embed link that has already been redeemed will be rejected.

The Embed Portal is not enabled by default. To request access, contact Pipe17 Support. Once enabled for your organization, you can proceed with API key creation and embed link generation.

Setting Up Embed Portal

Create an API Key for the Embed Portal

To support embed sessions, organizations should create a dedicated API Key named EMBED_KEY. The name must match exactly and is case sensitive.

The key must use the minimum permissions required to validate access, verify organization ownership, and manage the integration.

Required Permissions

The embed portal validates that the key name matches EMBED_KEY and that it has the required permissions.

Use Cases

Generate Links From the App

Once the API Key and feature flag are configured, users can generate embed links directly within an organization’s integration settings in the app.

Some connectors may rely on dynamic form components that are not yet supported. When this occurs, the option to generate an embed link may be unavailable with an explanatory note.

Generate Links Using the API

Third-party systems can also create embed links, but they must keep the EMBED_KEY secure in their backend. This key must never be exposed to merchants or frontend code. If the key is leaked, it could be used maliciously.

For merchants with multiple organizations, the third party must generate a unique session per organization.

To create a session, the third party sends the following request:

curl --location 'https://embed.pipe17.com/api/auth-code' \
--header 'Content-Type: application/json' \
--header 'x-pipe17-key: {{EMBED_KEY}}' \
--data '{
  "orgKey": "{{EMBED_KEY_ORG_KEY}}",
  "permissions": [
    {
      "type": "integration",
      "integrationId": "{{INTEGRATION_ID}}",
      "scope": { "connection": true }
    }
  ]
}'

Sample Response

{
  "status": "success",
  "authCode": {
    "code": "b2lnKe1kZu",
    "orgKey": "{{EMBED_KEY_ORG_KEY}}",
    "expiresAt": "2025-04-25T19:51:08.183Z",
    "createdAt": "2025-04-23T19:51:08.183Z",
    "permissions": [
      {
        "type": "integration",
        "integrationId": "{{INTEGRATION_ID}}",
        "scope": { "connection": true }
      }
    ],
    "apikey": "{{EMBED_KEY}}"
  }

https://embed.pipe17.com/code/{{CODE}}

This link can be delivered to the merchant in any preferred method.

Embed Portal Architecture

The embed workflow allows a secure, temporary, and permission-scoped connection flow between a merchant, a third-party system, and the app.

---

Troubleshooting

• Embed link does not load
  Check that the embed link was not redeemed previously. Each link is valid for a single session.

• Merchant cannot save changes
  Verify that the EMBED_KEY includes update permissions for integrations.

• Session expired
  Generate a new embed link and send it to the merchant.

• Dynamic connector fields not visible
  Some connectors use advanced configuration components that are not yet supported in the embed portal. Make sure to contact the support team to enable the feature.

Need Help?

If you need additional assistance:

• Use Ask Pippen, our AI agent, located at the top of the app page.

• Submit a support request with as much relevant detail as possible. Learn how to submit a request.

• For urgent issues, email us directly at support@pipe17.com.

We're here to help you succeed with your operations.