Approval Matrix

The approval matrix governs who can approve what across the platform. It combines authority profiles (what a user is allowed to do), referral rules (when to escalate), and approval records (the decision trail). The system is implemented across two API route groups: apps/api/src/routes/authority.ts for profile and rule management, and apps/api/src/routes/approvals.ts for the approval workflow.

Authority Profiles

An authority profile defines the underwriting limits for a group of users. Profiles are scoped to an organization and ordered by level (1 = most junior, 10 = most senior).

Profile Fields

Field	Type	Description
`name`	string	Profile name (e.g., "Junior Underwriter", "VP Underwriting")
`level`	1--10	Authority tier -- higher levels can approve larger risks
`maxTiv`	number	Maximum total insured value this profile can bind
`maxLimit`	number	Maximum policy limit this profile can bind
`maxPremium`	number	Maximum premium this profile can bind
`authorizedLobs`	string[]	Lines of business the profile can underwrite
`prohibitedStates`	string[]	States where this profile cannot write
`canOverride`	boolean	Whether violations can be overridden (senior authority)
`constraints`	JSON	Additional org-specific constraints

CRUD Operations

# List all active profiles for an org
GET /v1/authority/profiles?orgId={orgId}

# Include inactive profiles
GET /v1/authority/profiles?orgId={orgId}&includeInactive=true

# Create a new profile
POST /v1/authority/profiles
{
  "orgId": "uuid",
  "name": "Senior Underwriter",
  "level": 3,
  "maxTiv": 5000000,
  "maxLimit": 2000000,
  "maxPremium": 100000,
  "authorizedLobs": ["commercial_auto", "general_liability"],
  "prohibitedStates": []
}

# Update a profile
PATCH /v1/authority/profiles/:id
{
  "maxPremium": 150000,
  "canOverride": true
}

User Assignment

Each user is assigned to exactly one active authority profile at a time. Assigning a user to a new profile automatically deactivates their previous assignment.

POST /v1/authority/profiles/:id/assign
{
  "userId": "uuid",
  "effectiveFrom": "2026-03-24T00:00:00Z",
  "effectiveTo": "2026-12-31T23:59:59Z",
  "notes": "Promoted to senior tier"
}

Assignments have optional effectiveFrom and effectiveTo dates. Expired assignments are automatically excluded from authority checks.

Profile Detail

The GET /v1/authority/profiles/:id endpoint returns the profile with its currently assigned users (userId, name, email, assignedAt, assignedBy).

Authority Check

The POST /v1/authority/check endpoint evaluates whether a specific user can perform a given action in context. This is called during submission processing to determine whether the underwriter can bind directly or must refer.

Request

{
  "userId": "uuid",
  "action": "bind",
  "context": {
    "tiv": 3500000,
    "premium": 75000,
    "limit": 1000000,
    "lob": "commercial_auto",
    "state": "FL"
  }
}

Evaluation Logic

The check evaluates five dimensions against the user's assigned authority profile:

Check	Condition	Violation Message
TIV	`context.tiv > profile.maxTiv`	"TIV $X exceeds limit of $Y"
Premium	`context.premium > profile.maxPremium`	"Premium $X exceeds limit of $Y"
Limit	`context.limit > profile.maxLimit`	"Limit $X exceeds authority of $Y"
LOB	`context.lob not in profile.authorizedLobs`	"LOB 'X' not authorized"
State	`context.state in profile.prohibitedStates`	"State 'X' is prohibited"

Decision Rules

Allowed: No violations found.
Allowed (override): Violations exist, but the profile has canOverride: true.
Allowed (refer): The action is refer -- referrals are always permitted regardless of violations.
Denied: Violations exist and the profile cannot override.

Response

{
  "data": {
    "allowed": false,
    "violations": ["TIV $3,500,000 exceeds limit of $2,000,000"],
    "authority": {
      "level": 2,
      "name": "Junior Underwriter",
      "canOverride": false,
      "maxTiv": 2000000,
      "maxPremium": 50000,
      "maxLimit": 1000000
    }
  }
}

Authority Matrix View

The GET /v1/authority/matrix?orgId={orgId} endpoint returns the complete authority grid for an organization -- all active profiles with their assigned users and the full set of lines of business in use. This powers the matrix view in the admin UI.

{
  "data": {
    "profiles": [
      { "level": 1, "name": "Assistant UW", "maxTiv": 1000000, "assigned_users": [...] },
      { "level": 2, "name": "Underwriter", "maxTiv": 3000000, "assigned_users": [...] },
      { "level": 3, "name": "Senior UW", "maxTiv": 10000000, "assigned_users": [...] }
    ],
    "lineOfBusinesses": ["commercial_auto", "general_liability", "cargo"]
  }
}

Referral Rules

Referral rules define the conditions under which a submission is automatically escalated. Rules are evaluated in priority order (lower number = higher priority) and can trigger referral, auto-approval, or auto-rejection.

Rule Fields

Field	Type	Description
`name`	string	Rule name
`priority`	number	Evaluation order (lower = first)
`conditions`	JSON	Condition object evaluated against submission data
`action`	enum	`refer`, `auto_approve`, or `auto_reject`
`targetAuthorityLevel`	number	Minimum authority level required to handle the referral
`targetProfileId`	uuid	Specific profile to route to (optional)
`notifyChannels`	array	Notification channels: `slack`, `email`, `in_app`
`slackChannel`	string	Slack channel for notifications
`notifyEmails`	array	Email addresses to notify
`escalationEnabled`	boolean	Whether to auto-escalate after timeout
`escalationHours`	number	Hours before escalation (default: 24)
`escalationLevel`	number	Authority level to escalate to

Example: High-TIV Referral Rule

POST /v1/authority/rules
{
  "orgId": "uuid",
  "name": "High TIV Referral",
  "priority": 10,
  "conditions": { "tiv": { "$gt": 5000000 } },
  "action": "refer",
  "targetAuthorityLevel": 4,
  "notifyChannels": ["slack", "email"],
  "slackChannel": "#uw-referrals",
  "notifyEmails": ["senior-uw@mga.com"],
  "escalationEnabled": true,
  "escalationHours": 12,
  "escalationLevel": 5
}

Rules are soft-deleted -- DELETE /v1/authority/rules/:id sets is_active to false.

Approval Workflow

When a submission exceeds an underwriter's authority or a referral rule triggers, an approval record is created in the approvals table.

Approval Types

Type	Entity Type	Trigger
`bind`	`submission`	Bind request exceeds underwriter's authority limits
`siu_referral`	`claim`	Special Investigations Unit referral
`reserve_change`	`claim`	Reserve change exceeds adjuster's authority
`bordereaux_submit`	`bordereaux`	Bordereaux submission requires sign-off

Creating an Approval

Approvals are created programmatically by the system (role: system or org_admin) when an action requires escalation:

{
  "orgId": "uuid",
  "type": "bind",
  "entityType": "submission",
  "entityId": "uuid",
  "workflowId": "workflow-instance-id",
  "requestedBy": "uuid",
  "metadata": { "submissionId": "uuid", "premium": 120000 },
  "expiresAt": "2026-04-01T00:00:00Z"
}

Decision Endpoint

POST /v1/approvals/:id/decide
{
  "decision": "approved",
  "decidedBy": "uuid",
  "notes": "Reviewed loss history, acceptable risk"
}

The endpoint enforces:

Idempotency: Already-decided approvals return 409.
Expiry: Expired approvals return 409.

Side Effects

Bind rejection: When a bind approval is rejected, the system reverts both the policy and the linked submission to declined status.

Workflow resumption: If the approval is tied to a Cloudflare Workflow instance (workflowId), the decision event is sent to the workflow to resume processing:

bind approvals send to BIND_WORKFLOW with event type underwriter-bind-approval.
reserve_change approvals send to CLAIM_WORKFLOW with event type claim.reserve_approved.

API Reference

Authority Endpoints

Method	Path	Description
`GET`	`/v1/authority/profiles`	List authority profiles
`POST`	`/v1/authority/profiles`	Create authority profile
`GET`	`/v1/authority/profiles/:id`	Get profile with assigned users
`PATCH`	`/v1/authority/profiles/:id`	Update profile limits
`POST`	`/v1/authority/profiles/:id/assign`	Assign user to profile
`GET`	`/v1/authority/rules`	List referral rules
`POST`	`/v1/authority/rules`	Create referral rule
`PATCH`	`/v1/authority/rules/:id`	Update referral rule
`DELETE`	`/v1/authority/rules/:id`	Soft-delete referral rule
`GET`	`/v1/authority/matrix`	Full authority matrix grid
`POST`	`/v1/authority/check`	Check user authority for action

Approval Endpoints

Method	Path	Description
`GET`	`/v1/approvals`	List approvals (paginated, filtered by status)
`POST`	`/v1/approvals`	Create approval record
`POST`	`/v1/approvals/:id/decide`	Approve or reject

Submission Work Queue -- Triage scoring and swimlane routing
Underwriting -- Rules engine and risk evaluation
Claims -- Reserve change approvals

Authority Profiles​

Profile Fields​

CRUD Operations​

User Assignment​

Profile Detail​

Authority Check​

Request​

Evaluation Logic​

Decision Rules​

Response​

Authority Matrix View​

Referral Rules​

Rule Fields​

Example: High-TIV Referral Rule​

Approval Workflow​

Approval Types​

Creating an Approval​

Decision Endpoint​

Side Effects​

API Reference​

Authority Endpoints​

Approval Endpoints​

Related​