Alpha Release Candidate

[clundie-CL]

Problem description
As a stepping stone towards a meta release and in view of incorporating zero-touch onboarding capabilities into the API, the group is pursuing an alpha release candidate for review.

Expected action
Create an alpha release branch that can incorporate PRs that iterate towards this goal. The scope of the alpha release is as follows.

• Refactor API to convert Isolated Networks to Trust Domains
• Restructure API_definitions to breakout models into standalone files that can be bundled with tools like redocly.
• Reduce security scope granularity per Overly complex scope hierarchy #78
• Misc refinements that address the review feedback received in Prepare r1.1 #73 and summarized in NAM API Review Response: Alpha Release Strategy and Technical Roadmap Discussion #77

Additional context
The original PR that resulted in recommendations to pursue alpha release: #73
The issue that summarizes review feedback into major/minor tasking: #77

[clundie-CL]

Consider #92 before this issue completion

[clundie-CL]

From AI review: Summary: Password handling in Trust Domain access details

Current state:

• WPA Personal and WPA Enterprise password fields are in request examples.
• Responses currently return passwords (or are undecided); schema uses writeOnly not consistently.
• No explicit obfuscation or redaction logic defined.

Problem:

• Potential leakage of sensitive credentials in read/list responses and logs.
• Ambiguity: clients may assume password is retrievable or immutable.
• Compliance and audit concerns (PII/security secrets retention).

Options to discuss:

• Keep single schema, mark password writeOnly (omit from all responses).
• Split request/response schemas (create variant with password; response variant without field).
• Return an obfuscated placeholder (e.g. "********") to signal presence without exposing value.
• Allow retrieval only via a privileged scope (adds conditional response logic).
• Move password out of access detail into a one‑time credential provisioning endpoint.

Pros/cons (high level):

• writeOnly (Option 1): simplest, widely supported; clients cannot read back original value.
• Split schemas (Option 2): clearer contract; extra maintenance.
• Placeholder (Option 3): conveys existence but may mislead about ability to update partially.
• Privileged scope (Option 4): flexible; increases complexity and surface for mistakes.
• Separate endpoint (Option 5): strongest isolation; more API surface, migration effort.

Questions for decision:

• Do clients need to verify stored password value after creation?
• Are passwords ever rotated or partially updated?
• Regulatory requirements to avoid storing or returning shared secrets?
• Need to distinguish “unset” vs “set” without exposing value?

Risks if unchanged:

• Accidental credential exposure via logs, caches, SDK models.
• Future breaking change if later removal is required.
• Inconsistent handling across access detail variants.

Recommendation (to evaluate):

• Adopt writeOnly password (Option 1) plus explicit docs: “Password never returned; update requires full replacement.”
• Provide an operation to rotate password via POST/PATCH where client supplies new value only.

Next steps:

• Confirm if password readback is a business requirement.
• Decide redaction model (omit vs placeholder).
• Update schema + examples accordingly.
• Add test ensuring responses never include password.
• Document rotation/update workflow.

Please discuss and record the chosen approach before further schema changes.

[clundie-CL]

Other general topic areas to check before calling this good:

• Need pagination on GETs that return arrays
• need query param filtering on GET list endpoints