Admin (operator)

The /v1/admin/* routes configure an Ark instance. They are called by back-office / operator tooling (and CI/CD pipelines), not by an end-customer integration, and they set up the tenant configuration that the customer-facing routes depend on.

The formal request/response schema for every route is on the API Reference; these pages are the operator's map of what each group does, how it authenticates, and the order to call things in.

Route groups

Group	What it manages	Page
Clients & brands	the tenant client / brand records that anchor everything else	clients
Products	the product catalogue and per-client/brand product mappings	products
External applications	OAuth2 applications and which clients/brands each may access	external-applications
Routing policies	which backing provider serves each capability for a client/brand	routing-policies
Configuration	the business-rule (BRE) definitions used for rule-driven decisions	configuration
Domain-object mapping	links an Ark resource to its record at a backing provider (onboarding existing data)	mapping

Authentication

Auth mode differs by group:

Group	Auth
Clients, Products, External applications, Routing policies	Microsoft Entra ID JWT bearer with the ADMIN role (machine-to-machine via the Client-Credentials grant)
Configuration	Entra ID JWT bearer with the ADMIN role (no API-key path)
Domain-object mapping	API key in the X-Api-Key header

Two rules that apply across the admin surface

• Most writes are idempotent PUT upserts by key — re-running a configuration step updates rather than duplicates, and a PUT re-activates a previously soft-deleted record. The exceptions are noted on each page (creating a provider is a POST; deleting a routing policy is deliberately not idempotent).
• Order matters. A client/brand must exist before you can map products to it, authorise an external application for it, or set its routing policies — those all reference an existing client slug. A backing provider must be registered in the catalogue before a routing policy can target it.

For the internal flow, validation, and persistence behind these routes, see the admin architecture notes.