​
How to embed a Dock workspace into your app

Account represents any external relationships, typically another company. The most common use case for an Account is your customer or sales prospect. Integration with external systems like Salesforce and HubSpot allows for seamless synchronization of account data, enhancing the management of client relationships and related business processes. All the accounts are associated with a company that can be accessed via the API. An account can also be created, updated via the API.

You’re a developer who has a SaaS application and you want to embed Dock within your application. The following guide will explain how to set up an onboarding experience for your customers.

Your “onboarding experience“ is an onboarding Dock workspace that’s associated with an account that has signed up for your app. Once you create the workspace template, you can now create workspaces for new accounts that sign up for your app.

Example:

  • OpenAI has signed up for your app.
  • After they signup you can create an onboarding workspace for them.
  • If you’re using Salesforce and OpenAI is associated with an account:
  • If you’re using HubSpot and OpenAI is associated with a company:
  • If you are using neither CRM you can manually create an Dock account:
  • In your application, you have a page where you want to embed the Dock workspace.
  • There’s a user signed in to your app (sam@openai.com). They are associated with the account, OpenAI.
  • You want to create an Authenticated Embed Url, for sam@openai.com, for the workspace you created for the account, OpenAI. (documentation)
  • This generated url will automatically log in sam@openai.com to the Dock workspace.

In order to embed a workspace in your app you must have access to the Dock API and the workspace that you want to embed must be published

​
To embed a workspace in your app, you’ll need to follow these steps:

The generated url is only valid for 2 minutes. If the url is not used within 2 minutes it will be invalid, and you will need to generate a new one. It can be used just once.

1

Use the API to get the authenticated embed url for a user

Implement a business logic in your app that hits the authenticated embed url api end point with the email of the user that you want to log in and the workspace id

2

Embed the url received in the response in an iframe

Use the url received in the response and embed it in an iframe in your app.

<iframe src="https://opeanai.dock.us/embed/acme-JxFWgdSeWad9?authToken=24193e14b10a3e8f359bb634ca8228b3fd196ad0d88350918106c2442cffd023"></iframe>

Once an authenticated embed url is generated it remains valid for 2 minutes. So, make sure to use it within 2 minutes.

3

Token verification and workspace access

Once the iframe is loaded the authToken in the url is exchanged with the server in order to authenticate the user. Once verified the user can access and interact with the workspace.