Skip to main content
Version: 1.0.0

Routing Policies Administration

Admin surface for the Connector Routing (CR) module. Three resources:

  1. Connector catalog — /v1/admin/connectors. The platform-wide list of connectors the routing engine can dispatch to. POST to register, DELETE to retire, GET to list active connectors.

  2. Per-client routing policies — /v1/admin/clients/{slug}/policies/{capabilityKey}. For each (client, capability) pair, the policy is the complete set of routing rules the platform will use to pick a connector at request time. PUT replaces the entire set in one atomic transaction.

  3. Capability catalog — /v1/admin/capabilities. Read-only enumeration of routing operations the platform knows about, used by the admin UI to populate dropdowns when authoring policies.

Routing flow​

Mental model for the admin​

A policy is a list of entries. Each entry pairs a facts map against an ordered list of targets (connector keys). At request time the platform takes the request's facts, finds the entry that matches, and tries each target in order.

  • facts: {} (empty) → the default entry, used when no other entry matches. Every policy needs either a default entry or every admissible (factKey, value) declared by the capability covered by an explicit pin.
  • facts: { contactChannel: "SMS" } → a pinning entry, matches only when the request carries that exact fact value.
  • targets: ["id-provider", "address-provider"] → try id-provider first; if unhealthy, fall over to address-provider.

Slug convention​

{slug} is the same URL-friendly identifier used by the admin-clients API (/v1/admin/clients/{slug}). The platform resolves it server-side to a (clientId, brandId) tenant pair; admins never deal with raw IDs directly.

Capability mechanisms​

mechanismResolution strategy
bindingSticky — routes to the connector that first handled the entity
policyRule-based — evaluates the tenant policy against request facts

Audit​

Every write captures the authenticated principal as createdBy / updatedBy / closedBy server-side. Retiring a connector reuses closedBy; there is no separate retiredBy column. Actor identity is never accepted from the request body or URL.

Authentication​

All endpoints require the ADMIN OAuth2 scope (client-credentials flow).

Error envelope​

{ errorCode, message, timestamp, traceId } where errorCode follows the pattern {DOMAIN}{CLASSIFICATION}{SEQUENCE} (e.g. CRT004001, CRT022001, CRT009004).

Authentication​

Security Scheme Type: oauth2
OAuth Flow (clientCredentials): Scopes:
  • ADMIN: Access to admin functionality
Last updated on