Summary
Embedding a customer portal link inside your own application improves collaboration, prevents lost links, and gives users quick one-click access to their Portal
Your app should check whether an end user has portal access using the Planhat API, display the portal link only to eligible users, and request a signed login URL when the user clicks it
The signed URL authenticates the user without credentials (valid for 30 seconds), after which Planhat replaces it with a proper session token and logs the user into the Portal
Who is this article for?
Planhat admins (e.g. CS Ops) who configure Portals for their organization
Series
Share Portals with your customers from within your own application ⬅️ You are here
Introduction
Customer portals are a compelling way to increase collaboration and create transparency between you and your customers.
When a customer portal is shared via a link, it can often get lost, requiring constant re-sharing. However, if you surface it inside your application, it can create a more efficient workflow and serve as a visual reminder to check on it more often.
This is why we provide you with the option to create a link tag to embed the portal within your own application or product. This “one-click” solution requires only a small amount of technical effort on your end, yet allows your end users to open the portal with a single click from within your app.
📌 Important to note
If you do not have access to the backend of your application, share this article with someone who can implement it for you.
Here’s how it works:
A. Show a link to the portal somewhere in your app
One-click access requires you to place a link to the portal within your app (e.g., a button labeled “Portal Link”). In most cases, not all of your end users will have access to your Planhat customer portal, so you only want to show this link or button to users who actually have access.
To know whether an end user has access (and whether you should show the button), call the Planhat API with your API token:
GET https://api.planhat.com/endusers/:enduserId/portal/checkaccess
Response: { hasAccess: true|false }
B. Redirect the user to a signed URL of the portal
This can be implemented in a few different ways, but a typical process looks like this:
B1. The user clicks the portal button in your app.
This triggers a request to your own API or backend service that includes the end user’s ID.
B2. Your backend server requests the signed URL.
Call this Planhat API endpoint (with your API token in the header):
GET https://api.planhat.com/endusers/:enduserId/portal/generateloginurl
Response: { hasAccess: true|false, loginUrl: string }
B3–B4. Open a new tab with the redirect URL
If the user is found and has access to their Portal, the API will return a link in the format:
https://ws.planhat.com/portal-login/{tenantSlug}/invitation/{redirectToken}
When opened, this link authenticates the user without requiring credentials. Please note that these links are short-lived and must be used within 30 seconds before they expire.
C. Portal Access
When the user is redirected, Planhat will validate the redirect URL and replace it with a proper session token. The user is then logged into the Portal.