Access and setup

Manual home · Role guides · Coverage · Gaps

Manual conventions and recovery apply to every workflow. Evidence level: code inspected; related tests were inspected, not executed.

flowchart TD
  A[Authenticate] --> B{Provider and tenant valid?}
  B -->|No| C[Correct account or provider configuration]
  B -->|Yes| D[Resolve current permissions]
  D --> E[Open authorised workspace]
  E --> F[Perform permitted work]
  F --> G[Sign out or session expires]

ACC-01 — Sign in, check tenant access and sign out

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: sign in, check tenant access and sign out.

Actors and access: All users; active local account, or a provisioned Auth0 organisation and token permissions.

Prerequisites: Know the tenant and its configured authentication provider.

Entry point: Application login; /api/v1/auth.

1. For local authentication, enter tenant, email and password. Sentinel creates a session; its browser client supplies CSRF protection for writes.
2. Load the session and check the displayed principal and workspace before starting work. Auth0 API access derives the tenant from its trusted organisation mapping.
3. Sign out using the application action; local logout requires a valid CSRF token. Sign in again after expiry.

Result: An authenticated tenant principal, or an ended local session.

Exceptions and recovery: Inactive accounts and provider mismatches fail. A tenant header cannot override Auth0 organisation scope. Throttled login attempts require waiting; a 403 requires an access/configuration correction, not repeated submission.

Source evidence: services/api/src/identity/routes.ts; services/api/src/identity/authenticator.ts; apps/web/src/features/auth/login.tsx.

ACC-02 — Invite members, revoke invitations and accept an invitation

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: invite members, revoke invitations and accept an invitation.

Actors and access: Owner/manager with members:manage; invitation acceptance uses its token.

Prerequisites: The tenant uses local accounts; any reserved teams exist.

Entry point: Settings → Users → Invitations; login invitation flow.

1. Create an invitation with email, role and optional team memberships. Only an owner can grant owner.
2. Check the pending invitation; revoke it if it should no longer be accepted.
3. The recipient follows the invitation flow and sets a password meeting the displayed requirements. Acceptance applies the reserved memberships.

Result: A pending/revoked invitation or an active member after valid acceptance.

Exceptions and recovery: Invalid, revoked or expired tokens cannot be accepted; issue a replacement. Existing-member conflicts require reviewing the directory. Do not assume invitations are automatically emailed in every deployment; see GAP-06.

Source evidence: services/api/src/identity/member-routes.ts; services/api/src/identity/account-flows.ts; services/api/src/identity/routes.ts; apps/web/src/features/settings/users.tsx.

ACC-03 — Request or initiate a password reset

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: request or initiate a password reset.

Actors and access: Account holder; members:manage for administrative reset, owner for another owner's reset.

Prerequisites: Local authentication and a valid reset delivery process.

Entry point: Login password reset; Settings → Users → member detail.

1. Request a reset from login, or select the member's password-reset action as an administrator.
2. Use the issued reset link/token without copying it into logs or documentation.
3. Submit the replacement password and then authenticate with it.

Result: The local password is replaced after valid token completion.

Exceptions and recovery: Expired or invalid tokens require a new request; request throttling is deliberate. Reset delivery is deployment-dependent (GAP-06). Auth0 accounts use their external identity provider.

Source evidence: services/api/src/identity/routes.ts; services/api/src/identity/member-routes.ts; services/api/src/identity/account-flows.ts.

ACC-04 — Find members and inspect their details

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: find members and inspect their details.

Actors and access: members:manage for full administration/detail; members:read for the active directory.

Prerequisites: Authenticated tenant access.

Entry point: Settings → Users; member/team pickers.

1. Filter the administration list by search, role, status and team, and page through results.
2. Open a member to inspect profile, team memberships, sign-in/session details and recent activity.
3. Use active-directory pickers when assigning work; directory access is narrower than member administration.

Result: The intended tenant member is identified without changing their account.

Exceptions and recovery: An empty filtered page is not evidence that the member does not exist; clear filters or continue paging. A missing administration permission cannot be bypassed by opening the URL.

Source evidence: services/api/src/identity/member-routes.ts; apps/web/src/features/settings/users.tsx; apps/web/src/features/settings/member-detail.tsx.

ACC-05 — Create and maintain member profiles, roles and account status

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: create and maintain member profiles, roles and account status.

Actors and access: members:manage; owner-only safeguards apply to owner accounts.

Prerequisites: Local account administration and an existing target company/division where used.

Entry point: Settings → Users → create/member detail.

1. Create a member directly or open a member and edit permitted profile, organisation and role fields.
2. Suspend/reactivate an eligible account for temporary access changes, or deactivate it when permanent access removal is intended.
3. Refresh the record and inspect its resulting status and activity.

Result: The member profile, role or active status is updated within the tenant.

Exceptions and recovery: Sentinel protects the last active owner, rejects self-suspension/deactivation, and restricts owner changes to owners. Deactivated accounts are not reactivated by import. Correct invalid company/division references before retrying.

Source evidence: services/api/src/identity/member-routes.ts; services/api/src/identity/owner-transition-guard.ts; apps/web/src/features/settings/member-detail.tsx.

ACC-06 — Import, export and bulk-maintain members

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: import, export and bulk-maintain members.

Actors and access: members:manage; the same owner and self-protection rules apply per member.

Prerequisites: A CSV matching the import fields; valid tenant team references.

Entry point: Settings → Users → Import/export and selected-row actions.

1. Upload/map member rows and run the dry-run preview. Resolve duplicate emails, invalid roles and team errors.
2. Choose invitation-first import or permitted existing-member upsert, including add/replace team behaviour; submit and inspect every row result.
3. Export filtered/selected members as CSV, or apply a bulk role/status action and review each result.

Result: Validated rows are imported or updated; export reflects the selected scope.

Exceptions and recovery: Bulk operations may partially succeed. Retry only failed rows after resolving errors. CSV export neutralises formula injection. Invitation/reset values must be handled privately; dry-run results do not establish successful import.

Source evidence: services/api/src/identity/member-routes.ts; apps/web/src/features/settings/member-import.tsx; apps/web/src/features/settings/users.tsx.

ACC-07 — Create teams, maintain memberships and archive or restore teams

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: create teams, maintain memberships and archive or restore teams.

Actors and access: teams:read to browse; teams:manage to create/edit/manage membership.

Prerequisites: Existing active tenant members and any associated company/division.

Entry point: Settings → Teams.

1. Create or edit a team with its name and organisation context.
2. Add or remove members using tenant member pickers; inspect the resulting membership.
3. Use the team update controls to archive/restore the team and review downstream assignment choices.

Result: Team metadata and membership are stored; archived teams remain historical records.

Exceptions and recovery: Choose valid tenant references. Archived teams may be excluded from new assignment/announcement choices; restore a team deliberately rather than recreating it to preserve history.

Source evidence: services/api/src/teams/routes.ts; apps/web/src/features/settings/teams.tsx; packages/contracts/src/teams.ts.

ACC-08 — Maintain companies and divisions

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: maintain companies and divisions.

Actors and access: teams:read to list; teams:manage to create/edit.

Prerequisites: A tenant organisation structure to represent.

Entry point: Settings → Company.

1. Create the company or open its existing record.
2. Edit permitted details and configured divisions.
3. Use the resulting company/division in member and team assignments and reporting filters.

Result: Tenant companies/divisions are available for organisation scoping.

Exceptions and recovery: A division must belong to the selected company when assigning a member. This interface does not expose a company deletion workflow; do not infer one from other administration screens.

Source evidence: services/api/src/companies/routes.ts; apps/web/src/features/settings/companies.tsx.

ACC-09 — Configure workspace behaviour and retention

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: configure workspace behaviour and retention.

Actors and access: members:manage to read settings; owner/platform override for owner-gated writes; audits:manage for review-assignment policy.

Prerequisites: An owner has agreed retention, timezone and processing choices.

Entry point: Settings → Workspace.

1. Review workspace settings and set the tenant timezone and retention policy, including separate unredacted media retention.
2. Configure transcription language, channel roles, sensitivity, terminology and vocabulary profiles; changes feed new job snapshots.
3. Set supported enrichment, interaction-display, journey-coaching and review-assignment controls using their own permission gates.

Result: Saved workspace defaults apply according to each feature's snapshot/lookup behaviour.

Exceptions and recovery: Do not assume edits rewrite existing transcription snapshots or historical published records. Shorter retention can lead to cleanup (OPS-11). Journey coaching defaults off; enable only after the rollout evidence gates are satisfied.

Source evidence: services/api/src/app.ts; apps/web/src/features/settings/workspace.tsx; docs/transcriber-managed-policy.md.

ACC-10 — Set personal preferences

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: set personal preferences.

Actors and access: Authenticated user with qms:read; preferences are user-scoped.

Prerequisites: A current tenant session.

Entry point: Preferences; theme/language/timezone controls.

1. Open preferences and inspect effective versus stored settings.
2. Choose supported language, theme, timezone or other offered preferences and save.
3. Reload a relevant screen and check the effective formatting; an unset personal timezone uses the tenant default.

Result: The user's presentation preferences are saved.

Exceptions and recovery: Preferences do not change tenant policy or other users' settings. If the effective value differs, inspect tenant/default fallback and reload rather than changing workspace settings unintentionally.

Source evidence: services/api/src/user-preferences/routes.ts; apps/web/src/features/preferences/preferences.tsx; packages/contracts/src/user-preferences.ts.