Skip to main content

Approval Action Portal

The Approval Action Portal enables recipients to approve or deny requests directly from notification links without logging into Control Bridge. This page explains how the one-click action flow works from both Email and Teams channels.

How It Works​

From Email​

When a recipient clicks an Approve or Deny button in a notification email:

  1. The browser opens the Approval Action Portal with the action token
  2. The portal displays a confirmation page showing:
    • The approval type (for example, "Email Reply Approval")
    • The action being taken (for example, "You are about to approve this email reply")
    • A summary of the approval item with relevant details
    • An optional text field for notes or denial reasons
  3. The recipient clicks Confirm to execute the action
  4. A success page confirms the action was processed

This two-step confirmation prevents accidental actions from email link pre-fetchers or unintended clicks.

From Microsoft Teams​

When a recipient clicks Approve or Deny on a Teams Adaptive Card:

  1. The action is processed inline within Teams (no browser redirect)
  2. The original card is replaced with a result card showing:
    • Whether the action succeeded
    • The action that was taken (approved/denied)
    • Who processed it and when
  3. No additional confirmation step is required (the Teams card button serves as the confirmation)

Action Token Lifecycle​

Each notification generates unique action tokens that follow a strict lifecycle:

Token Created (notify)
       |
       v
Token Active (waiting for action)
       |
       +---> Token Expired (ExpiresAt passed)
       |         |
       |         v
       |     Error page / error message
       |
       +---> Token Consumed (recipient clicks action)
                 |
                 v
            Action Executed in Source System
                 |
                 v
            Sibling Tokens Invalidated
                 |
                 v
            NotificationLog Updated

Sibling Token Invalidation​

When any token for an approval item is consumed, all other tokens for that same item are immediately invalidated. This prevents scenarios where:

  • Multiple recipients both approve the same item
  • A recipient approves via email after another recipient already denied via Teams
  • The same recipient clicks both approve and deny

After sibling invalidation, attempting to use an invalidated token displays a message indicating the action has already been processed.

Error States​

When a token cannot be used, the portal displays an appropriate error page:

ScenarioMessage Displayed
Invalid token"This action link is invalid. It may have been corrupted in transit."
Expired token"This action link has expired. Please check the admin console to take action."
Already used token"This action has already been processed."
Rate limited"Too many requests. Please wait a moment and try again."
Already resolved"This item has already been resolved." (The approval was handled via the admin console before the token was used.)

In all error cases, the recipient can still take action by logging into Control Bridge and using the appropriate review queue.

Rate Limiting​

The Approval Action Portal applies rate limiting to prevent abuse:

LimitThresholdWindow
Per IP address30 requests1 minute
Per token5 attempts1 hour

If rate limits are exceeded, the portal returns a "Too Many Requests" page. The recipient should wait briefly and try again, or take action through the admin console instead.

Approval Type Details​

Each approval type displays different context information and executes different actions when confirmed.

Escalations​

Context shown: Agent name, escalation reason, conversation summary (truncated)

On approve: The escalation is resolved with an "approved" decision, and the waiting agent resumes with the human's guidance.

On deny: The escalation is resolved with a "denied" decision, and the agent receives the denial along with any feedback provided.

Safety Reviews​

Context shown: Agent name, tool being used, risk level, safety rule triggered

On approve: The flagged tool execution is released and proceeds as planned.

On deny: The tool execution is blocked and the agent is notified of the denial.

Email Approvals​

Context shown: Agent name, email action type (reply/forward/send), email subject, sender, recipients

On approve: The email is sent as the agent proposed.

On deny: The email is discarded and the agent is notified.

Agent Creation​

Context shown: Proposed agent name, description, who requested it, SME topics

On approve: The new agent is created with the proposed configuration.

On deny: The creation request is rejected and logged.

QuickBooks Write Approvals​

Context shown: Agent name, operation type, entity type and name, proposed changes

On approve: The financial write operation is executed in QuickBooks.

On deny: The write operation is cancelled.

Security Considerations​

The Approval Action Portal is designed to be accessed without authentication (since recipients may not be logged into Control Bridge when they click an email link). Security is maintained through:

  • Token entropy - Action tokens are UUID v4 values with 128-bit entropy, making them computationally infeasible to guess
  • Single-use enforcement - Tokens are atomically marked as used with a WHERE UsedAt IS NULL guard to prevent race conditions
  • CSRF protection - The confirmation page requires an explicit POST request to execute the action. The token itself serves as the CSRF token since an attacker would need knowledge of the token to forge the request.
  • IP logging - Every action records the IP address of the actor for audit trail purposes
  • Rate limiting - Both IP-based and token-based limits prevent brute-force attempts
warning

Action tokens are sensitive. They grant the ability to approve or deny requests without authentication. Do not share notification emails or forward them to untrusted recipients. If you suspect a token has been compromised, take action on the approval item through the admin console to invalidate all outstanding tokens.

Monitoring Actions​

All notification deliveries and actions are logged in the NotificationLog. Each log entry records:

  • The notification channel used (Email or Teams)
  • The recipient
  • Delivery status (sent, failed, or skipped)
  • When the action token was consumed (if applicable)
  • The IP address of the actor
  • The action taken (approve or deny)

NotificationLog entries are retained for 1 year for compliance and audit purposes.