Broker API

External-facing API for licensed brokers and agents — submit quotes, manage client portfolios, track commissions, and operate within a delegated authority limit.

Overview

The Broker API is a specialised gateway that allows licensed brokers and agents to interact with Olly's enrollment and policy systems on behalf of their clients. It enforces a broker or broker-admin Keycloak role on every request and extracts a brokerId claim from the JWT to scope all operations to the authenticated broker's book of business.

Brokers can create and advance quotes through the underwriting workflow (delegating to Enrollment), view and manage their client policy portfolio, create client accounts and parties in Policy Admin, track commissions earned on issued policies, and operate within a delegated authority limit that caps the maximum premium they can bind without additional approval.

Commission records are local to the Broker API database. Portfolio queries proxy through to Enrollment. Client management proxies to Policy Admin. This keeps the broker-specific concerns (commissions, authority limits) isolated while reusing existing service capabilities for core operations.

Responsibilities

• Authenticate brokers via JWT with broker/broker-admin role and brokerId claim
• Allow brokers to create and advance quotes through pricing, underwriting, and issuance
• Provide a portfolio view of policies associated with the broker's book
• Allow brokers to create client accounts and parties in Policy Admin
• Track and pay commissions for issued policies
• Enforce delegated authority limits on premium amounts
• Expose eligibility checks for client coverage lookups

Database

Schema: broker

Table	Purpose
broker_configs	Delegated authority limits and configuration per broker ID
commissions	Commission records per issued policy, with payment status

API Routes

All routes require JWT authentication with the broker or broker-admin role.

Method	Path	Auth	Description
POST	/quotes	JWT + broker role	Create a quote for a client (proxies to Enrollment)
GET	/quotes/{locator}	JWT + broker role	Get quote status
PATCH	/quotes/{locator}/price	JWT + broker role	Price a quote
PATCH	/quotes/{locator}/underwrite	JWT + broker role	Underwrite a quote
PATCH	/quotes/{locator}/issue	JWT + broker role	Issue a quote into a policy
GET	/portfolio/policies	JWT + broker role	List all policies in the broker's portfolio
GET	/portfolio/policies/{locator}	JWT + broker role	Get a specific policy in the portfolio
POST	/clients/accounts	JWT + broker role	Create a client account in Policy Admin
POST	/clients/parties	JWT + broker role	Create a client party in Policy Admin
GET	/commissions	JWT + broker role	List commissions for the broker
POST	/commissions	JWT + broker role	Record a new commission
GET	/commissions/{locator}	JWT + broker role	Get commission by locator
PATCH	/commissions/{locator}/pay	JWT + broker role	Mark a commission as paid
GET	/authority	JWT + broker role	Get the broker's delegated authority configuration
PUT	/authority	JWT + broker-admin role	Set or update delegated authority limit

Events

Publishes

The Broker API does not publish Kafka events.

Consumes

The Broker API does not consume Kafka events.

Dependencies

Service	How used
Enrollment	Quote creation, advancement, and portfolio policy listing
Policy Admin	Client account and party creation
Eligibility	Client coverage lookups

Key Design Decisions

Broker scoping via JWT claim: Every API call is automatically scoped to the authenticated broker's brokerId claim. Brokers cannot query or modify resources belonging to other brokers — the middleware enforces this before any handler logic runs.

Commissions are local, portfolio is proxied: Commission tracking is the only data the Broker API owns. Portfolio views proxy directly to Enrollment's policy data rather than duplicating it. This avoids data consistency issues and keeps the broker database small.