This article covers the 2.0 portal. If you want to embed the classic Compass portal, see this article Embedded Onboarding Portal.

Example code

A working reference implementation lives in our public demo repository: https://github.com/guidecx/embed-demo.

It shows the full flow: minting the embed token on a server, building the iframe, and handling session expiry.

How it works

Your backend calls the GUIDEcx API to mint a short-lived embed token for a customer user.
Your page renders an iframe whose src points at the GUIDEcx embed sign-in URL, carrying that token.
GUIDEcx signs the customer in and shows the portal for the requested project, with no app navigation.

The embed token is valid for one minute and identifies one customer user.

Mint a fresh token every time you render the iframe.

Keep your API token on the server.

Only the short-lived embed token may reach the browser.

Never expose your GUIDEcx API token in client-side code.

Step 1: Invite your customers to their projects

Customers must exist in GUIDEcx as customer users on the project you want to embed.

The embedded portal shows exactly what that customer is allowed to see, so permissions are managed in GUIDEcx, not in your site.

Step 2: Mint an embed token

Call the token endpoint from your backend with the customer's email address:

curl -X POST https://api.guidecx.com/api/v3/members/embed-token \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "customerUserEmail": "customer@example.com" }'

The response is wrapped in a data envelope and includes every project that customer can access:

{
  "data": {
    "embedToken": "embed...",
    "projects": [
      { "id": "6b4d3c2a-...", "name": "Acme Implementation" }
    ]
  }
}

Use the embedToken and the id of the project you want to show.

A customer with no projects returns an empty projects list, which is a valid response, not an error.

Step 3: Add the iframe to your page

Place the portal wherever it fits your navigation, for example behind an "Onboarding" or "Implementation" menu item:

<iframe
  src="https://app.guidecx.com/embed/customer-login/sso?token=EMBED_TOKEN&projectId=PROJECT_ID&page=today&email=CUSTOMER_EMAIL"
  width="100%"
  height="1200"
  frameborder="0"
  title="Onboarding Portal">
</iframe>

Inject token, projectId, and email dynamically from the values your backend received in Step 2.

The email is the same customer email you minted the token for.

The `page` parameter

page chooses which portal tab the customer lands on:

Value	Shows
`today`	The customer's current tasks (default)
`overview`	Project overview and progress
`messages`	Project messages
`attachments`	Files and attachments

If page is omitted or unrecognized, the portal opens on today.

The 1.0 value notes is still accepted and lands on messages, so existing deep links keep working after a migration.

Step 4: Allow GUIDEcx in your Content Security Policy

GUIDEcx already allows its embed pages to be framed, so nothing is needed on our side.

If your site sets a Content Security Policy, add app.guidecx.com to your frame-src directive so the browser lets your page load the iframe.

How you do this depends on your technology stack.

Until it is configured, the browser blocks the frame and shows a connection error in its place.

Handling session expiry

Embedded sessions eventually expire, and only your backend can mint a new token.

When the customer navigates on an expired session, the portal shows them a friendly "Your session has ended" page and posts a message to your page:

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://app.guidecx.com') return

  if (event.data?.type === 'guidecx:embed-session-expired') {
    // Mint a new embed token on your backend,
    // then set the iframe src again to sign the customer back in.
  }
})

Listening for this message is optional but recommended: it lets you refresh the session automatically instead of asking the customer to reload your page.

What your customer sees

The portal fills the frame with no GUIDEcx app navigation, project switcher, or banners.
Navigation between portal tabs happens inside the frame, and the session persists across it.
If the customer follows a link to a GUIDEcx page that has no embedded equivalent, they see a "not available here" page with a Go back button that returns them to the portal with their session intact.

Sessions work in browsers that block third-party cookies.

The embedded session is also isolated to your site: it does not sign the customer into GUIDEcx anywhere else, and other GUIDEcx sessions in the same browser do not interfere with your embed.

Email deep link configuration

Customer notification emails (project overview, task reminders and assignments, mentions, overdue tasks) can point to your embedded portal path instead of the GUIDEcx URL, so email links keep customers inside your site.

Contact your GUIDEcx representative to configure your portal URL for the workspace.

Migrating from the 1.0 embed

The query parameters are identical, so migrating is one URL change on each side:

	1.0 (Compass)	2.0
Token endpoint	`POST /api/v2/users/embed-token`	`POST /api/v3/members/embed-token`
Token response	`{ embedToken, projects }`	`{ data: { embedToken, projects } }`
Iframe URL path	`/auth/customer-login/sso`	`/embed/customer-login/sso`
Pages	`today, notes, attachments`	`today, overview, messages, attachments`
Sign-in failures	JSON error inside the frame	A readable error page inside the frame
Session expiry	Not signaled	`guidecx:embed-session-expired` message

Notes on the differences:

The v3 endpoint uses a different API token than the legacy v2 endpoint. If your existing token gets a 401 from v3, request a current API token from your GUIDEcx admin settings.
page=notes maps to messages automatically, so deep links do not need to change.
The 1.0 embed keeps working unchanged. You can run both versions side by side, including on the same page, while you migrate.

FAQ

Which project views can be embedded?

The 2.0 Customer Portal.

The full project view used by your internal team is not embeddable.

How do customers switch between multiple projects?

Each iframe shows one project.

The token response lists every project the customer can access, so you can render your own project picker and reload the iframe with a new token and the chosen projectId.

Can I embed the 1.0 and 2.0 portals at the same time?

Yes.

Their sessions are independent, so you can migrate gradually or show them side by side while testing.

Why is a customer still blocked from the portal?

A few rare situations prevent embed sign-in: the customer belongs to multiple GUIDEcx accounts, holds both provider and customer roles, or is related through a third party.

The frame shows an explanatory page rather than signing them in.

Why don't I see embed options in my account?

Embedding is included in our advanced tier and can be added to other tiers for an additional fee. Talk to your GUIDEcx representative.

Embedded Onboarding Portal 2.0