Public Portal

The Public Portal provides secure, token-based access for clients to interact with scoping questionnaires and SOW documents without requiring a SPEAR account.

Portal Access

Token-Based Authentication

All public portal access uses secure tokens:

• Token Format: Cryptographically secure random strings
• Validation: Tokens are validated on every request
• Expiry: Links expire after a configurable period (default: 7 days)
• Single-Use Options: Certain actions invalidate tokens after use

Access Control

Portal access is controlled by:

1. Valid Token - Link must contain unexpired token
2. Status Validation - Scoping session must be in appropriate state (e.g., sent, viewed for SOW viewing)

Note: Email authorization is only enforced when adding or deleting comments on SOW documents. Viewing SOWs, viewing questionnaires, submitting questionnaire responses, and accepting/rejecting SOWs require only a valid, unexpired token.

Generating Access Links

Sales team generates links from the Scoping Workbench:

1. Navigate to scoping session
2. Go to Send tab
3. Click Generate Link
4. Set expiry period
5. Copy and share link with client

Public Questionnaire Portal

URL Format: /public/scoping/{token}

The questionnaire portal allows clients to complete scoping questionnaires externally.

🖥️ Public Questionnaire Portal Interface Screenshot

Accessing the Questionnaire

1. Client receives questionnaire link
2. Opens link in browser
3. Questionnaire loads if token is valid and unexpired

Questionnaire Interface

Client Information Display

• Client organization name
• Engagement description
• Selected services overview

Question Sections

Questions are organized by service:

• Section headers identify the service
• Questions appear in configured order
• Required fields are marked with asterisk

Question Types

Type	Interface
Text	Text input or textarea
Number	Numeric input with validation
Boolean	Yes/No toggle buttons
Select	Dropdown menu
Multi-Select	Checkbox group

Conditional Questions

• Questions may appear based on previous answers
• Smooth transitions when questions show/hide
• Validation adjusts dynamically

Submitting Responses

1. Complete all required questions
2. Enter contact name (required)
3. Optionally enter contact email
4. Click Submit Questionnaire

On submission:

• Responses are saved to the scoping session
• Status updates to scoping
• Sales team receives notification
• Confirmation message displays

CSRF Protection

All form submissions are protected:

• CSRF token generated on page load
• Token validated on submission
• Prevents cross-site request forgery attacks

Rate Limiting

Action	Rate Bucket
View questionnaire	Relaxed (read operations)
Submit questionnaire	Strict (write operations)

Read operations (GET) use a relaxed rate limit bucket (100 requests/hour). Write operations (POST) use a strict rate limit bucket (10 requests/minute).

Public SOW Portal

URL Format: /public/sow/{token}

The SOW portal allows clients to review, comment on, and accept/reject SOW documents.

🖥️ Public SOW Portal View Screenshot

Accessing the SOW

1. Client receives SOW access link
2. Opens link in browser
3. SOW loads if token is valid and unexpired

First View Tracking

When a client first views the SOW:

• Timestamp recorded
• Status updates to viewed (if currently sent)
• View count incremented
• Sales team can see view activity

SOW Display

Header Section

• Client logo (if uploaded)
• Document title (SOW or ROE)
• Version number
• Validity date

Content Sections

• Sections displayed in configured order
• Shortcodes resolved to actual values
• Formatting preserved from editor
• Images and tables rendered

Pricing Summary (SOW only)

For Statement of Work documents:

• Line items with descriptions
• Hours and rates (if shown)
• Subtotal, overhead, tools
• Grand total
• Validity period

Version Comparison

If SOW version > 1:

• View Changes button appears
• Side-by-side comparison available
• Changed sections highlighted
• Previous version accessible

Client Commenting

Clients can add comments to specific sections.

🖥️ Client Commenting Interface Screenshot

Adding a Comment

1. Navigate to section
2. Optionally highlight specific text
3. Click Add Comment
4. Enter comment text
5. Enter your name and email
6. Click Submit Comment

Comment Requirements

Field	Validation
Comment text	Required, max 2000 characters
Author name	Optional
Author email	Required, must match authorized recipient list

Note: Unlike viewing or accepting/rejecting SOWs, adding and deleting comments requires email validation. This ensures only authorized recipients can comment on the document.

Comment Display

• Comments appear near relevant section
• Author name and timestamp shown
• Highlighted text (if any) indicated
• Comment thread for discussions

Deleting Comments

• Authors can delete their own comments
• Email must match original author
• Deletion is permanent

SOW Acceptance

To accept the SOW:

1. Review all sections
2. Click Accept SOW
3. Enter signature name (legal name)
4. Confirm acceptance

On acceptance:

• Status updates to accepted
• Acceptance timestamp recorded
• Signatory name recorded
• Client IP address logged
• Confirmation displayed
• Sales team notified

SOW Rejection

To reject the SOW:

1. Click Reject SOW
2. Enter rejection reason (required)
3. Confirm rejection

On rejection:

• Status updates to rejected
• Rejection timestamp recorded
• Reason stored for sales review
• Confirmation displayed
• Sales team notified

Security Features

🎨 Token Validation Pipeline Diagram Illustration

Token Validation

Comprehensive token security:

Token Check Pipeline:
1. Format validation (length, characters)
2. Existence check in database
3. Expiry verification
4. Associated record status check

Email Validation (Comments Only)

Email authorization is enforced only for adding and deleting comments:

• Valid email format required
• Comparison is case-insensitive
• Email must match the authorized recipient list configured by the sales team

Note: Viewing documents, submitting questionnaires, and accepting/rejecting SOWs do not require email validation—only a valid, unexpired token.

CSRF Protection

All state-changing operations require CSRF tokens:

Operation	CSRF Required
View content	No
Submit questionnaire	Yes
Add comment	Yes
Accept SOW	Yes
Reject SOW	Yes

Token lifecycle:

1. Token generated on page load
2. Stored in client session
3. Submitted with form data
4. Validated on server
5. Regenerated after use

Rate Limiting

Tiered rate limiting protects against abuse:

Endpoint Type	Rate Bucket	Description
Read operations (GET)	Relaxed	100 requests/hour
Write operations (POST/DELETE)	Strict	10 requests/minute

All write operations—including questionnaire submission, adding/deleting comments, and accept/reject actions—share the strict rate limit bucket.

Audit Logging

All portal activities are logged:

• Access attempts (success/failure)
• Email validation attempts
• Comment additions/deletions
• Acceptance/rejection events
• IP addresses and timestamps

Error States

Invalid Token

"This link is invalid or has expired."

Causes:

• Token doesn’t exist
• Token has expired
• Token was revoked

Unauthorized Email (Comments Only)

"Email not authorized for this SOW"

Causes:

• Email not in the authorized recipient list when attempting to add a comment
• Email format invalid
• Typo in email address

Note: This error only occurs when adding comments. Viewing documents and accepting/rejecting SOWs do not require email authorization.

Session Expired

"Your session has expired. Please refresh the page."

Causes:

• CSRF token expired
• Server session timeout
• Browser cache issues

Already Accepted/Rejected

"This SOW has already been [accepted/rejected]."

Causes:

• Another recipient completed the action
• Manual status change by sales team

Best Practices

For Sales Teams

Link Management

• Use appropriate expiry periods
• Track link generation in notes
• Revoke unused links promptly

Recipient Configuration

• Add all decision makers
• Use verified email addresses
• Update list as contacts change

Client Communication

• Explain the portal process
• Provide support contact info
• Set expectations for response time

For Clients

Accessing Documents

• Use the email address that received the link
• Check spam folder if link doesn’t work
• Contact sender if access issues persist

Providing Feedback

• Use comments for specific questions
• Be clear and specific in feedback
• Include context with comments

Acceptance Process

• Review all sections before accepting
• Use legal/authorized name for signature
• Save confirmation for records

Troubleshooting

”Link not working”

1. Check link hasn’t expired
2. Verify email address is correct
3. Clear browser cache
4. Try incognito/private window
5. Contact sender for new link

”Can’t submit questionnaire”

1. Ensure all required fields completed
2. Enter a contact name (required)
3. Check for validation errors
4. Try refreshing the page

”Comments not saving”

1. Verify email matches authorized list
2. Check comment length (max 2000 chars)
3. Ensure stable internet connection
4. Try refreshing and resubmitting

”Accept button disabled”

1. SOW may already be accepted/rejected
2. Token may have expired
3. Check with sales team for status