Approval Routes

Approval Routes in TraceMem are reusable configurations that define the logical routing of approval requests. They specify which integration to use, where to send approval requests, and what requirements apply.

Key Principle: Approval Routes are the logical layer between policies (which require approvals) and integrations (which deliver them).

What Approval Routes Are

An Approval Route is:

• A reusable configuration for approval delivery
• A link between policies and integrations
• A definition of approval requirements (rationale, expiration)
• A routing rule (which integration, where to send)
• A named, versioned artifact

It answers:

"When an approval is needed, which integration should be used, where should it be sent, and what are the requirements?"

What Approval Routes Are Not

An Approval Route is not:

• An integration (routes reference integrations, they don't deliver)
• A policy (routes are used by policies, they don't define when approvals are needed)
• An approval authority (routes route, they don't approve)
• A workflow engine
• A replacement for business logic

Approval Routes provide the "where" and "what" of routing. Integrations provide the "how" of delivery.

Approval Route Components

An Approval Route defines:

1. Integration Reference - Which integration to use (Slack, Email, Webhook)
2. Route Destination - Where to send (Slack channel, email address, webhook uses integration URL)
3. Require Rationale - Whether approvers must provide a reason
4. Expiration Time - How long the approval request is valid
5. Name - Human-readable identifier for the route

Example:

{
  "approval_route_id": "apr_route_finance_01",
  "name": "Finance approvals",
  "integration_id": "int_slack_01",
  "route": "#finance-approvals",
  "require_rationale": true,
  "expires_in_seconds": 86400
}

Approval Route Lifecycle

1. Creation

Approval Routes are created by administrators via:

• The Admin Dashboard
• The Admin API

Agents cannot create or modify Approval Routes.

2. Configuration

When creating an approval route:

• Select an integration (must be configured first)
• Specify the route destination (channel, email, or uses webhook URL)
• Set approval requirements (rationale, expiration)
• Provide a descriptive name

3. Attachment to Policies

Approval Routes are attached to policies that return requires_exception:

{
  "policy_id": "discount_cap_v1",
  "exception_route": {
    "approval_route_id": "apr_route_finance_01"
  }
}

When the policy requires an exception, the attached approval route is used.

4. Status Management

Approval Routes have status:

• active - Route is available for use
• disabled - Route is temporarily disabled

Disabled routes cannot be used by new policies, but existing references remain valid for audit purposes.

How Approval Routes Work

Routing Flow

Policy Evaluation
    ↓ (requires_exception)
Approval Route Selected (from policy)
    ↓
Integration Identified (from route)
    ↓
Route Destination Determined
    ↓
Approval Requirements Applied
    ↓
Integration Delivers Request

Route Selection

When a policy returns requires_exception:

1. Policy's exception route is checked
2. Approval Route is retrieved
3. Integration is identified from the route
4. Route destination is determined
5. Approval requirements (rationale, expiration) are applied
6. Request is delivered via integration

Requirement Overrides

Approval requirements can be set at multiple levels:

1. Approval Route - Default requirements
2. Policy - Can override route requirements
3. Agent Request - Can make requirements more strict (but not less)

The most strict requirement wins.

Route Types

Slack Routes

Routes approval requests to Slack channels:

{
  "integration_id": "int_slack_01",
  "route": "#finance-approvals"
}

• Uses Slack integration
• Route is the Slack channel name
• Interactive buttons for approve/reject

Email Routes

Routes approval requests to email addresses:

{
  "integration_id": "int_email_01",
  "route": "finance@example.com"
}

• Uses Email integration
• Route is the email address
• Magic-link approval in email

Webhook Routes

Routes approval requests to webhook endpoints:

{
  "integration_id": "int_webhook_01"
}

• Uses Webhook integration
• Route is determined by the webhook integration URL
• Custom webhook delivery

Relationship to Other Concepts

Approval Routes → Policies

Policies attach Approval Routes to define exception handling:

• Policies return requires_exception
• Policies reference an Approval Route
• When exception is needed, the route is used

Example:

{
  "policy_id": "discount_cap_v1",
  "exception_route": {
    "approval_route_id": "apr_route_finance_01"
  }
}

Approval Routes → Integrations

Approval Routes reference Integrations for delivery:

• Routes specify which integration to use
• Integrations handle the technical delivery
• One integration can serve multiple routes

Approval Routes → Approvals

Approval Routes configure how approvals are requested:

• Routes define where approval requests go
• Routes define approval requirements
• Routes are recorded in approval events

Approval Routes → Decision Traces

Approval Routes are recorded in decision traces:

• Which route was used
• Which integration delivered
• What requirements applied
• Where the request was sent

Best Practices

1. Use descriptive names - Indicate purpose and team (e.g., "Finance approvals", "Support escalations")
2. Set appropriate expiration times - Balance urgency with approver availability
3. Require rationale for important approvals - Capture why approvals were granted/rejected
4. One route per team/channel - Separate routes for different approval contexts
5. Test routes after creation - Verify routing works correctly
6. Document route purposes - Help administrators understand when to use each route
7. Disable instead of deleting - Preserve historical references in traces

Mental Model

Approval Routes are the address labels.
Policies are the reason for sending.
Integrations are the postal service.
When a policy says "this needs approval", it looks at the address label (route) to see where to send it.
The address label says "use this postal service (integration) and send it to this address (route destination)".
The postal service delivers it, and the recipient responds.
The address label doesn't care what's in the envelope or why it's being sent—it just says where it should go.