Admin endpoints — routing policies

Controls which backing provider serves each capability for a client/brand. A policy maps a capability (e.g. send-SMS, verify-identity) to a target provider, optionally with a default, so the platform knows which provider to route each customer request to (see overview → how requests are routed). This group also maintains the catalogue of providers a policy can target.

Auth: Entra ID JWT bearer with the ADMIN role. The formal schema is on the API Reference.

Policies (per client/brand)

Method	Path	Code	Does
GET	/v1/admin/clients/{slug}/policies	200	List all of the tenant's policies
PUT	/v1/admin/clients/{slug}/policies	200	Replace the tenant's full policy set
GET	/v1/admin/clients/{slug}/policies/{capabilityKey}	200	Read the policy for one capability
PUT	/v1/admin/clients/{slug}/policies/{capabilityKey}	200	Replace the policy for one capability
DELETE	/v1/admin/clients/{slug}/policies/{capabilityKey}	204	Remove the policy for one capability

Provider catalogue

The set of backing providers a policy may target, exposed as the connectors resource.

Method	Path	Code	Does
GET	/v1/admin/connectors	200	List the registered (active) providers
POST	/v1/admin/connectors	201	Register a provider
PATCH	/v1/admin/connectors/{connectorKey}/base-url	200	Update a provider's base URL
DELETE	/v1/admin/connectors/{connectorKey}	204	Retire a provider

Capabilities

Method	Path	Code	Does
GET	/v1/admin/capabilities	200	List the capabilities (and their inputs) a policy can target

Notes for operators

• Order. Register a provider before any policy targets it — a policy write that names an unregistered or retired provider is rejected. The client slug must already exist.
• Policy writes are all-or-nothing. A PUT (single capability or full set) is validated as a whole and applied atomically; a single invalid entry rejects the entire call with 422 CRT022001 and changes nothing. Runtime routing never observes a half-applied policy.
• Deleting a policy is deliberately not idempotent. Removing a capability that has no active policy returns 404 CRT004001 rather than succeeding silently, so an accidental repeat call is visible.
• Registering a provider is create-only. POST /connectors is not an upsert — a duplicate connectorKey returns 409 CRT009004.
• Retiring a provider is a soft-delete. It is refused with 409 CRT009002 while any active policy still targets it. Customer requests already pinned to a retired provider continue to reach it; only new policy writes that target it are blocked.

Errors

HTTP	Code	When
404	CRT004004	Client slug not found
404	CRT004001	No active policy for the capability (read or delete)
404	CRT004003	Provider not found, or already retired (update base URL)
409	CRT009002	Provider still targeted by an active policy (retire)
409	CRT009003	Provider is retired; update rejected
409	CRT009004	Provider connectorKey already exists (register)
422	CRT022001	Policy validation failed (wrong mechanism, empty set, missing/duplicate target, fact-coverage gap, or unknown target provider)