Separate everyday integration from application administration
The reference distinguishes ordinary application operations from operations reserved exclusively for administrators of the application itself. Readers can focus on the contract relevant to their work.
Example — A tenant integration reads the normal API
An integration developer uses organization-scoped operations in the normal reference. Platform-level administration operations appear in their own section; organization administration is not automatically application administration.
For engineers
The projector examines each operation’s resolved access authorities. Only a non-empty set consisting exclusively of application-administration roles selects the administration reference. Mixed-authority operations remain in the normal reference; scope names alone do not determine the split.
The generator owns one filename map for both formats:
export const OPENAPI_OUTPUT_FILENAMES: Readonly<Record<OpenApiSection, Readonly<{ yaml: string; json: string }>>> = {
[OpenApiSection.API_REFERENCE]: {
yaml: 'api.yaml',
json: 'api.json',
},
[OpenApiSection.APPLICATION_ADMINISTRATION_API_REFERENCE]: {
yaml: 'application-administration-api.yaml',
json: 'application-administration-api.json',
},
};
This is the actual generator contract, not an application override. The publication service writes the emitted sections to the stable reference tree and the portal consumes them. A section with no operations is omitted rather than published as an empty promise.
Preserve one classification decision
Do not repartition operations again in the frontend based on guessed role names or URL paths. The renderer should consume the section selected by projection. Separating reference navigation does not add authorization: runtime operation access remains enforced by the backend, and the publication policy governs what documentation may be public.