[HDR-6545] Document Issuer Hierarchy changes on Public API Team Members and Departments endpoints

[shravi903]

🎟 Ticket

HDR-6545 — documentation task covering two stories in the HDR-6012 epic:

• HDR-6013 (BE sub-task HDR-6097) — Team Members: new fields + key-kind authorization
• HDR-6014 (BE sub-task HDR-6098) — Departments: scoped API key enforcement

⛔ Do not merge yet

This documents behaviour that has not shipped. All three backend PRs are still open:

• accredible/accredible-credential-api#5277 — team members create + serializer fields
• accredible/accredible-credential-api#5284 — team members update
• accredible/accredible-credential-api#5290 — departments key scope

There are also three places where these docs describe intended behaviour that the backend does not yet implement — see the table at the bottom. Each needs a backend change, or the published docs will be wrong.

📝 What does this PR do?

Documents the Issuer Hierarchy changes across the four Team Members operations and the five documented Departments operations. Follows the structure of #130 (the pathways field): additive schema properties, matching example bodies, updated cURL samples, plus prose for the authorization rules.

Team Members — POST /v1/team_members, GET/PUT/DELETE /v1/team_members/{id}

• Response schemas + examples (all four) gain the six serializer fields after groups: api, team, spotlight_directory, access_level, analytics_email, manage_dept_admins_and_devs.
• Request schemas + examples (POST, PUT) gain the five accepted params: api, team, access_level, analytics_email, manage_dept_admins_and_devs. spotlight_directory is response-only and is deliberately not in the request schema.
• access_level is enumerated — request side to the three assignable values with default: "team_member", response side to all four wire values.
• Two tables added to the Create and Update descriptions: which key kind may create which access_level, and the permitted permission values per tier.
• cURL samples regenerated directly from the request examples so the two cannot drift.

Departments — POST /v1/departments, GET/PUT/DELETE /v1/departments/{department_id}, POST /v1/departments/search

No schema changes — this story is authorization only, so it is prose in each operation's description. GET, PUT and DELETE previously had no description at all.

Operation	Account-wide key	Department-specific key
POST /v1/departments	full access	403 No Permission to manage Departments.
GET /v1/departments/{id}	any Department	own only; others 404 No department found
PUT /v1/departments/{id}	any Department	own only; others 404 No department found
DELETE /v1/departments/{id}	full access	403 No Permission to manage Departments.
POST /v1/departments/search	all Departments	scoped to its own Department

Also included

• Drive-by bug fix: the four Team Members response schemas and examples said department_id, but Api::V1::Public::TeamMemberSerializer emits department. Corrected in the schemas, the required arrays and the examples. Requests correctly keep department_id. This bug predates this ticket.
• PUT clarifications: the payload replaces the member's entire permission set (a Department omitted from the array has its permission removed, which requires an account-wide key), and email has been dropped from the request schema since it is ignored.
• GET /v1/departments (index) is affected by HDR-6014 but has never been documented here. Left out — adding a new endpoint is separate work.
• Adds an internal planning note under docs/plans/. Happy to drop it from the branch if we'd rather not carry it in a public-facing repo.

No error-response objects

The authorization rules are documented in prose only. This spec documents error responses almost nowhere today (a single 422 on POST /v2/credentials/bulk_create), so adding 400/403/404 objects to these operations only would be an inconsistent one-off. Happy to revisit if reviewers prefer otherwise.

✅ How this was verified

• openapi.json parses; the diff touches only the intended operations.
• Scripted check: the documented permissions keys match TeamMemberSerializer exactly on all four responses and team_member_params exactly on both requests; each example body matches its own schema's key set; the request examples obey the permitted-values table they document; each cURL body is byte-identical to its request example; no department_id remains in any response.
• The permitted-values table was derived by brute-forcing all field/role combinations through PermissionLocks#locks_for layered on the public-API defaults and allowlist, then cross-checked against permission_locks_spec.rb — not written by hand.
• Rendered locally with Redoc to confirm the tables and descriptions display correctly.

🪙 Type of change

• 📦 Chore/Documentation

✅ Checklist

• PR title includes Jira ticket
• At least 2 reviewers requested
• Ready to squash and merge — blocked on the three backend PRs above

[cloudflare-workers-and-pages]

Deploying accredible-api-documentation with    Cloudflare Pages

Latest commit:	8dec21e
Status:	✅  Deploy successful!
Preview URL:	https://ce3f8d01.accredible-api-documentation.pages.dev
Branch Preview URL:	https://feature-hdr-6545-update-api.accredible-api-documentation.pages.dev

View logs