How to Embed your portal

When hosting your Rocketlane solution on a private network (on-premises), it will generally function as expected. However, you'll need to whitelist Rocketlane's domains and IP addresses.

Thereon, Rocketlane’s Customer Portal can be embedded directly into your product, allowing your customers to view project progress, receive notifications, and collaborate without ever leaving your application. This creates a seamless experience and ensures that all customer-facing project information is presented natively within your platform.

This article walks you through the steps to embed the portal using an iframe and implement secure, token-based access using JWT (JSON Web Tokens).

Step 1: Navigate to Embed Instructions

1. Log in to your Rocketlane workspace.

2. Go to Settings > Customer Portal > Embed Customer Portal.

3. Follow the on-screen instructions to get started with embedding.

Step 2: Embed the Portal in Your Product

To embed the customer portal in your UI, insert the following HTML snippet where you want the portal to appear:

<iframe src="https://xy.rocketlane.com/cp/embed?token=<jwt_token>">
  <a href="https://xy.rocketlane.com/cp/embed?token=<jwt_token>">Go to Portal</a>
</iframe>

• The iframe embeds the portal into your UI.

• The <a> link provides a fallback option, allowing users to access the portal in a new tab if iframe rendering fails.

• Replace xy with your workspace subdomain and insert a valid JWT token for authentication.

Step 3: Secure the Portal with JWT Authentication

Rocketlane uses JWTs to authenticate users accessing the embedded portal. This enables a smooth login experience without requiring separate passwords.

Benefits of JWT-Based Login

• Seamless one-click login from within your product

• No email invite or manual login required

• Secure, time-limited access

Authentication Options

Rocketlane supports two methods for JWT authentication:

1. Shared Secret Key (Simpler Setup)

• Rocketlane provides a shared secret.

• You use this key on your backend to sign tokens and authenticate users.

2. Public/Private Key Pair (Higher Security)

• Generate a private/public key pair.

• Add your public key to Rocketlane via Settings.

• Sign JWTs on your server using your private key.

Note: You can choose to use one key across all customer or can can have different keys for each customer.

Step 4: Generate a JWT Token

Here’s a sample Python function to generate a JWT token using your private key:

import jwt
def generate_jwt_token(your_private_key, email_id, project_id, hash_param, expires_at):
    payload = {
        "user": {
            "emailId": email_id,
            "emailLanguagePreference": "EN"  # Supported: EN, DE, FR, IT, ES, NL
        },
        "config": {
            "projectId": project_id,
            "inviteIfAbsent": True,
            "hashParam": hash_param
        },
        "exp": expires_at
    }


    jwt_token = jwt.encode(payload, your_private_key, algorithm="HS256")
    return jwt_token

Key Payload Fields Explained:

• emailId: The customer’s email ID.

• emailLanguagePreference: Sets the language used in system-generated emails. You can select between English, German, French, Italian, Spanish and Dutch.

• projectId (optional): ID of the project the customer is accessing.

• inviteIfAbsent: Automatically invites the customer if they are not already part of the project.

• hashParam: A hash used to validate redirection (fetched from the email invite URL).

Step 5: Fetch Project ID (if needed)

If you need to dynamically fetch the projectId, use the Rocketlane API:

GET https://api.rocketlane.com/api/1.0/projects?externalRefKey=<????>
Headers:
  Accept: application/json
  api-key: <your_rl_api_key>

Where,

1. Endpoint: https://api.rocketlane.com/api/1.0/projects 

2. Query Parameter: Changed from companyName=YourCompanyName to companyId=<YourCompanyId>.

3. Make sure to replace <YourCompanyId> with the actual ID of your company and <your_rl_api_key> with your actual Rocketlane API key.

4. Headers:

   • accept: application/json to specify that you expect JSON responses.

   • api-key: <your_rl_api_key> where <your_rl_api_key> should be replaced with your actual API key.

Read more about Rocketlane APIs here.

Step 6: Set the Email Redirection URL

To ensure email links take customers to your embedded portal, configure the Email Redirection URL:

1. Go to Settings > Customer Portal > Customer Portal Invite Configuration.

2. Scroll down to the Email Redirection URL.

3. Enter the URL where your customer portal iframe is embedded—e.g., https://yourapp.com/projects/portal.

This ensures that when customers receive invite emails, clicking the link redirects them to your product, not Rocketlane’s default portal page.