Client Portal

Overview

The client portal provides a read-only (or review-capable) view of engagement deliverables for your clients. It is accessible via a shareable link and does not require your client to create a Groundtruth account or log in.

Use the portal to share finished deliverables with stakeholders, collect feedback through comments, and run formal approve/reject review cycles — all without giving external users access to your tenant dashboard.

Generating a Portal Token

Step-by-step (admin perspective)

1. Navigate to the engagement detail page for the engagement you want to share.
2. Open the Portal Token Manager section (below the deliverables list).
3. Fill in the following fields:
   • Label — a human-readable name for this token (e.g., "Acme Corp review link" or "Board review — Q1 strategy").
   • Permission level — controls what the client can do in the portal (see Permission Levels below).
   • Expiration date (optional) — if set, the token becomes invalid after this date. Recommended for time-limited reviews.
4. Click Create Token.
5. The token value is displayed once on creation. Copy it immediately. It cannot be retrieved again after you close the dialog.

The portal URL takes the form:

https://groundtruth-platform.vercel.app/portal/{token}

Send this full URL to your client via email, Slack, or your preferred channel.

What your client sees

When a client opens the portal URL, they land on a branded page showing:

1. Engagement header — your tenant logo, the engagement name, and client name
2. Deliverables list — all client-facing deliverables, with task names, content previews, and approval status badges (pending, approved, rejected, revision requested)
3. Internal engine files (logs, run reports) are automatically filtered out

Clicking a deliverable opens its full markdown content rendered in a readable format. A Provenance section at the bottom shows which AI agent and model produced the deliverable.

Permission Levels

Each portal token is created with one of three permission levels:

Which level to choose

You can create multiple tokens for the same engagement with different permission levels. For example, give the project lead view_approve access and the broader team view_only.

Portal Features

Deliverable viewing

Each deliverable is rendered as formatted markdown with:

• Proper heading hierarchy
• Tables and lists
• Code blocks (if applicable)
• Inline images (if referenced)

Comments (view_comment and view_approve)

If the token has commenting permissions, the client can:

• Leave comments on individual deliverables
• Comments are threaded per deliverable (not per paragraph)
• Comments include the commenter's name (entered on first comment) and timestamp

How comments flow to you: When a client leaves a comment, the tenant admin receives an email notification with the comment content, the deliverable it was left on, and a direct link back to the engagement. If webhooks are configured, a portal.comment event is dispatched.

Approve / Reject (view_approve only)

If the token has approval permissions, the client sees Approve and Reject buttons on each deliverable:

• Approve marks the deliverable as approved. The status badge updates immediately.
• Reject opens a text field for rejection notes. The client must explain what needs to change.
• Request Revision is a softer alternative — signals the deliverable needs work without a hard reject.

Approval status is visible to both the client (in the portal) and the tenant admin (on the engagement detail page).

PDF Export

Clients can download deliverables as formatted PDFs directly from the portal. Two optional toggles are available:

PDF export is available for individual deliverables and for the full engagement report.

Tenant Branding

Your tenant's branding is applied to the portal:

• Logo — displayed in the portal header
• Primary color — used for buttons, links, and accent elements
• Company name — shown in the header alongside the engagement name

Configure branding in Settings → Branding. Changes take effect immediately on all portal links.

Managing Tokens

From the Portal Token Manager on the engagement detail page, you can:

• View all tokens created for that engagement, including their label, permission level, creation date, and expiration status
• Revoke any token at any time. Once revoked, the portal URL immediately stops working for anyone who has it
• See usage status — whether a token has been accessed and when

Token lifecycle

Token Security Best Practices

1. Set expiration dates — especially for time-limited reviews. A 30-day expiry is a reasonable default.
2. Use the minimum permission level — don't grant view_approve if you only need feedback (view_comment).
3. Revoke tokens when done — after the review cycle completes, revoke the token. There's no cost to creating a new one later.
4. Create separate tokens per stakeholder group — this lets you revoke access for one group without affecting others.
5. Don't share tokens in public channels — portal tokens grant unauthenticated access. Treat them like passwords.
6. Rotate tokens periodically — for long-running engagements, create new tokens monthly and revoke old ones.

Email Notifications and Webhooks

When a client interacts with the portal:

Webhook events are dispatched only if configured (Settings → Webhooks). Email notifications go to the tenant admin.

Integration with Approval Workflows

The portal's approve/reject mechanism integrates with the platform's deliverable approval workflow:

1. You run an engagement and deliverables are produced
2. You create a portal token with view_approve permission
3. The client reviews deliverables in the portal
4. The client approves some deliverables and rejects others with notes
5. You see the updated approval status on the engagement detail page
6. For rejected deliverables, you can edit the task and trigger a targeted re-run
7. The re-run produces a new version of the deliverable
8. The client reviews again through the same portal link (if not expired)

Frequently Asked Questions

Can I have multiple portal tokens for the same engagement? Yes. Create as many as you need with different permission levels and expiration dates.

Can I change the permission level of an existing token? No. Revoke the existing token and create a new one with the desired permission level.

What happens if I revoke a token while someone is viewing the portal? Their current page remains visible until they navigate or refresh. After that, they see an "invalid token" error.

Can clients see each other's comments? Yes. All comments on a deliverable are visible to anyone with a valid token that has commenting permissions.

Does the portal work on mobile? Yes. The portal is responsive and works on mobile browsers. PDF download may have limitations on some mobile devices.

Can I customize the portal URL domain? Not currently. The portal is served from the platform's domain. Custom domains are on the roadmap for Enterprise plans.

How long does a portal token last if I don't set an expiration? Indefinitely, until you manually revoke it. Setting an expiration is recommended.

Can the client download the raw markdown? Not directly. PDF export is the supported download format. The client can copy text from the rendered view.

Related Guides

• Deliverables — managing deliverable versions, diffs, and approval workflows within the dashboard
• Team Management — controlling who on your team can create portal tokens and manage engagements
• Troubleshooting — resolving portal access issues