admin/_docs/02_document/components/05_admin_api/description.md

Admin API

1. High-Level Overview

Purpose: HTTP API entry point — configures DI, middleware pipeline, authentication, authorization, CORS, Swagger, and defines all REST endpoints using ASP.NET Core Minimal API.

Architectural Pattern: Composition root + Minimal API endpoints — top-level statements configure the application and map HTTP routes to service methods.

Upstream dependencies: User Management (IUserService), Authentication & Security (IAuthService, Security), Resource Management (IResourcesService), Data Layer (IDbFactory, ICache, configs).

Downstream consumers: None (top-level entry point, consumed by HTTP clients).

2. Internal Interfaces

BusinessExceptionHandler

Method	Input	Output	Async	Error Types
TryHandleAsync	HttpContext, Exception, CancellationToken	bool	Yes	None

Converts BusinessException to HTTP 409 JSON response: { ErrorCode: int, Message: string }.

3. External API Specification

Cycle 1 (2026-05-13) note — endpoints below reflect the post-cycle-1 surface (AZ-513 Detection Classes CRUD, AZ-196 device auto-provisioning, AZ-197 hardware-binding removal). AZ-183 (OTA) shipped in cycle 1 but was reverted later the same day after the security audit (finding F-1) — the OTA delivery model itself was deemed obsolete. For per-endpoint cycle origins see modules/admin_api_program.md.

Authentication

Endpoint	Method	Auth	Description
/login	POST	Anonymous	Validates credentials, returns JWT

User Management

Endpoint	Method	Auth	Description
/users	POST	ApiAdmin	Creates a new user
/devices	POST	ApiAdmin	AZ-196: provisions a CompanionPC device user (returns serial + email + plaintext password once)
/users/current	GET	Authenticated	Returns current user
/users	GET	ApiAdmin	Lists users (optional email/role filters)
/users/queue-offsets/set	PUT	Authenticated	Updates queue offsets
/users/{email}/set-role/{role}	PUT	ApiAdmin	Changes user role
/users/{email}/enable	PUT	ApiAdmin	Enables user
/users/{email}/disable	PUT	ApiAdmin	Disables user
/users/{email}	DELETE	ApiAdmin	Removes user

Removed by AZ-197: PUT /users/hardware/set (Hardware-binding feature deleted)

Resource Management

Endpoint	Method	Auth	Description
/resources/{dataFolder?}	POST	Authenticated	Uploads a file (up to 200 MB)
/resources/list/{dataFolder?}	GET	Authenticated	Lists files
/resources/clear/{dataFolder?}	POST	ApiAdmin	Clears folder

Removed by AZ-197: POST /resources/check (was the hardware-binding side-effect probe). Removed in post-cycle-1 revert: POST /get-update and POST /resources/publish (AZ-183 reverted — security audit F-1; OTA delivery model itself obsolete). Removed in cycle 2 (2026-05-14): POST /resources/get/{dataFolder?}, GET /resources/get-installer, GET /resources/get-installer/stage — all obsolete; the encrypted-download support stack (Security.GetApiEncryptionKey / EncryptTo / DecryptTo, ResourcesService.GetEncryptedResource / GetInstaller, GetResourceRequest, WrongResourceName = 50, ResourcesConfig.SuiteInstallerFolder / SuiteStageInstallerFolder) was removed with them. ADR-003 retired.

Detection Classes

Endpoint	Method	Auth	Description
/classes	POST	ApiAdmin	AZ-513: creates a detection class
/classes/{id:int}	PATCH	ApiAdmin	AZ-513: partial-merge update of a detection class
/classes/{id:int}	DELETE	ApiAdmin	AZ-513: deletes a detection class

Authorization Policies

• apiAdminPolicy: requires ApiAdmin role (used on most admin endpoints)

The apiUploaderPolicy was added by AZ-183 and removed in the post-cycle-1 revert along with the OTA endpoints it guarded. RoleEnum.ResourceUploader remains as data only.

CORS

• Allowed origins: https://admin.azaion.com, http://admin.azaion.com
• All methods/headers, credentials allowed

4. Data Access Patterns

No direct data access — delegates to service components.

5. Implementation Details

State Management: Stateless — ASP.NET Core request pipeline.

Key Dependencies:

Library	Version	Purpose
Swashbuckle.AspNetCore	10.1.4	Swagger/OpenAPI documentation
FluentValidation.AspNetCore	11.3.0	Request validation pipeline
Serilog	4.1.0	Structured logging
Serilog.Sinks.Console	6.0.0	Console log output
Serilog.Sinks.File	6.0.0	Rolling file log output

Error Handling Strategy:

• BusinessException → BusinessExceptionHandler → HTTP 409 with JSON body.
• UnauthorizedAccessException → thrown in resource endpoints when current user is null.
• FileNotFoundException → thrown when installer not found.
• FluentValidation errors → automatic 400 Bad Request via middleware.
• Unhandled exceptions → default ASP.NET Core exception handling.

6. Extensions and Helpers

None.

7. Caveats & Edge Cases

Known limitations:

• All endpoints are defined in a single Program.cs file — no route grouping or controller separation.
• Swagger UI only available in Development environment.
• CORS origins are hardcoded (not configurable).
• Antiforgery disabled for resource upload endpoint.
• Root URL (/) redirects to /swagger.

Performance bottlenecks:

• Kestrel max request body: 200 MB — allows large file uploads but could be a memory concern.

8. Dependency Graph

Must be implemented after: All other components (composition root).

Can be implemented in parallel with: Nothing — depends on all services.

Blocks: Nothing.

9. Logging Strategy

Log Level	When	Example
WARN	Business exception caught	BusinessExceptionHandler logs the exception
INFO	Serilog minimum level	General application events

Log format: Serilog structured logging with context enrichment.

Log storage: Console + rolling file (logs/log.txt, daily rotation).

Modules Covered

• AdminApi/Program
• AdminApi/BusinessExceptionHandler