Authority Doc / Public V1 Access

Roles and permissions define who can act, in which context, on which CoachMe data.

This page is the source of truth for Public V1 roles, operating contexts, permission gates, surface-specific access checks, support/admin access, and mobile cache boundaries. Feature pages can add local implementation detail, but they must not grant access that conflicts with this authority.

Coach WorkspaceCoach-Client RelationshipPersonal WorkspaceSupport/Admin Audit

Note

Public V1 supports coach workspace, coach-client relationship, personal workspace, and support/admin contexts. A single user account can hold multiple roles or contexts, but every request must choose one active context. Permissions do not bleed between contexts.

Permission Formula

Role alone never grants access. Every request must satisfy the full context and data rule.

Access Is Granted Only When Every Gate Passes

authenticated user + selected operating context + role + workspace/relationship ownership + lifecycle state + app surface + data/source rule

Backend Authorization Is Final

UI route guards and generated clients can improve user experience, but backend authorization is the final authority for every read, mutation, upload, playback, export, delete, worker action, and sync acceptance.

Gate	Meaning
authenticated user	Identity is verified through the configured auth provider session.
selected operating context	The request acts as coach workspace, coach-client relationship, personal workspace, or support/admin.
role	The actor's role inside the selected context.
workspace/relationship ownership	The target resource belongs to the selected context.
lifecycle state	The workspace, relationship, invitation, assignment, message, or media state permits the action.
app surface	The action is allowed from coach web, coach mobile, client/personal mobile, API/worker, or support/admin tooling.
data/source rule	The data category has no stricter rule that blocks the action.
synthetic production identity	A protected internal marker restricts release-smoke identities to their pre-provisioned synthetic workspace and relationship. Backend authorization denies real-user discovery, invitation, selection, messaging, and cross-workspace access even when the base coach or client role would normally permit the action.

Public V1 Actors

Public V1 keeps current roles narrow while naming future roles so they do not accidentally inherit broad access.

Actor	Public V1 Meaning	Default Authority	Constraint
Workspace Owner	Solo coach or owner of a coach workspace.	Manage workspace settings, templates, clients, assignments, and authorized client data.	Cannot access unrelated workspaces or client relationships.
Coach User	User operating inside a coach workspace.	Public V1 behaves like owner/solo coach unless later staff roles are enabled.	Future staff permissions must not be implied.
Coached Client	Client acting through a coach-client relationship.	Access own onboarding, Today tasks, logs, messages, progress, and allowed profile fields.	Cannot browse workspace internals or other clients.
Personal Workspace Owner	User managing self-coaching context.	Manage own self-coaching tasks, logs, progress, nutrition, reminders, and private data.	Cannot access coached-client records through personal context.
Dual-Context User	One account with multiple valid contexts.	Switches between contexts deliberately.	Permissions never merge across contexts.
Support/Admin Operator	Internal operator handling support, safety, legal, or diagnostics.	No default product access.	Requires explicit grant, reason code, target scope, and audit event.
Production Developer	Named internal engineer operating approved production telemetry.	Read minimized Grafana/Sentry operational evidence through a named account.	MFA and least privilege required; no default product-record, raw-receipt, payload, repair, replay, or mutation access.
Assistant/Staff	Future workspace collaborator role.	Not available in Public V1.	Reserved Post-V1; must not receive broad coach access accidentally.

Operating Contexts

Every request chooses one active context, except identity-scoped endpoints that run before context selection. Context selection must be explicit in API, worker, sync, and UI flows.

Coach Workspace Context

Requires workspace_id and valid workspace membership. It grants only the workspace actions and relationship access allowed by lifecycle and data rules.

Coach-Client Relationship Context

Requires relationship_id. The relationship must belong to the selected workspace and pass lifecycle gates before reads, writes, review, messaging, or sync acceptance.

Personal Workspace Context

Requires personal_workspace_id. It is a real Public V1 permission context for self-coaching data, and it cannot read or mutate coached-client relationship records.

Support/Admin Context

Requires operator_user_id, target resource, permission grant, reason code, and audit record. Normal product roles do not imply support access.

Production Telemetry Context

Requires a named individual account, MFA, and least-privilege provider role. It may search approved internal ids in minimized telemetry, but it grants no support/admin or product-data authority.

Worker Context

Workers act from accepted events, scheduled jobs, or idempotent sync operations, not from a human session. Worker actions still enforce target workspace, relationship, lifecycle, and data rules.

Identity-Scoped Endpoints

Device registration, listing, and revocation are scoped to the authenticated user account and app surface only. They run before context selection and grant no workspace, relationship, or personal workspace authority.

Dual-Role Separation

Dual-role accounts do not merge permissions. Coach workspace access does not unlock coached-client data elsewhere, and personal workspace access does not unlock coach-managed records.

Lifecycle Permission Gates

Access follows the canonical lifecycle map. State changes can remove permissions even when role and ownership still match.

Workflow state map

State	Permission Effect
CoachWorkspace ACTIVE	Normal coach workspace operations are allowed.
CoachWorkspace SUSPENDED	Block new invitations, publishing, provider configuration, and non-essential coach mutations. Allow limited reads, support review, and client continuity where policy permits.
CoachWorkspace CLOSED	Block normal coach operations. Retain, export, delete, or anonymize records through privacy and retention rules.
CoachClientRelationship INVITED / ONBOARDING	Client can register and onboard. Coach can view invite and onboarding status and prepare review. Assignment publishing remains gated by readiness.
CoachClientRelationship ACTIVE	Normal coach-client reads, assignments, review, messaging, and client execution are allowed.
CoachClientRelationship PAUSED	Keep read access and selected communication. Suppress or restrict reminders, risk escalation, and new assignment pressure.
CoachClientRelationship ENDED	Remove coach edit access immediately. Stop client sync push and pull for that relationship. Allow retained-history read only where privacy and retention policy permits.
CoachClientRelationship DELETED_OR_ANONYMIZED	No normal product access, including client sync push and pull. Only export, deletion, anonymization, legal, or support workflows remain.
PersonalWorkspace ACTIVE	User can manage self-coaching resources without coach visibility.
PersonalWorkspace SUSPENDED / CLOSED	Mirror workspace restrictions, scoped only to self-coaching data.

Surface Capability Matrix

Each app surface has a Public V1 capability boundary. Backend authorization still enforces the final rule.

Surface	Allowed Public V1 Authority	Public V1 Limit
Coach Web	Full creation and management for authorized coach workspace and active relationship contexts.	Must enforce workspace, relationship, lifecycle, and data-source gates.
Coach Mobile	Review, messaging, task inbox, client context, progress, nutrition review, risk signals, and lightweight actions.	No full builder parity in Public V1.
Client/Personal Mobile	Coached-client execution and Public V1 personal workspace self-coaching execution and management.	Cannot expose coach-only notes, internal risk scores, raw diagnostics, or unrelated relationship data.
API/Workers	Same permission gates as UI, plus event, schedule, and idempotency checks.	Workers do not inherit broad human access.
Support/Admin	Scoped troubleshooting, safety, legal, export/delete, moderation, or diagnostics workflows.	No ambient access; reason-coded and audited.

Data-Specific Permission Matrix

Protected data types add stricter rules on top of role, ownership, lifecycle, and surface gates.

Data Category	Owning Context	Allowed Reads	Allowed Writes	Restricted Actions	Audit Requirement
Identity and invitations	Coach workspace invite flow bound to one verified contact.	Workspace owner/coach reads active invites; invited user reads own claim state.	Workspace owner/coach sends, resends, revokes, and claims only for the bound contact.	No client invite browsing, no cross-contact reassignment, no broad support inspection.	Audit resend, revoke, claim conflicts, and any inactive invite inspection grant.
Workspace settings and templates	Coach workspace setup; personal workspace owner manages self-coaching defaults.	Workspace owner/coach reads full setup; clients read only published snapshots tied to their relationship or personal workspace.	Workspace owner/coach updates setup and templates; personal workspace owner updates own templates.	No client editing, no cross-workspace template reads, no assistant/staff inheritance.	Audit support/admin inspection or template export outside normal product flow.
Client profile, health, goals, allergies, injuries	Client-owned record inside an active coach-client or personal workspace context.	Client reads own record; authorized coach reads active relationship data; personal workspace owner reads own self record.	Client updates allowed fields; coach records review notes or approved plan inputs; ended relationships remove coach edits.	No unrelated coach access, no silent support mutation, no cross-context sharing.	Audit support/admin inspection, redaction, export, or exceptional correction.
Private coach notes	Authorized coach workspace relationship only.	Assigned coach and workspace owner read notes for that active relationship.	Assigned coach and workspace owner create, edit, and archive notes in that relationship.	Never visible to client, personal workspace, inactive relationships, or broad support roles.	Audit any exceptional support/admin access, export, or redaction.
Forms and onboarding	Assigned coach-client relationship or personal workspace self-coaching flow.	Client reads assigned forms and own submissions; authorized coach reads assigned responses; personal workspace owner reads self-forms.	Coach assigns and reviews; client submits own forms; personal workspace owner creates and submits self-forms.	No unassigned form browsing, no cross-client reads, no staff/admin default review access.	Audit support/admin inspection, reassignment, export, or submission correction.
Programs and workouts	Coach workspace program library or personal workspace self plan.	Authorized coach reads assigned plans and workspace-scoped workout history; client reads assigned plans and own logs through its own relationship sync slice; personal workspace owner reads own plans and logs.	Coach creates and publishes in coach web; client logs assigned work; personal workspace owner creates and logs own plans.	No coach mobile builder parity in Public V1, no silent rewrite of client performance logs, no cross-context cloning.	Audit support/admin inspection, rollback, export, or log correction.
Nutrition	Active coach-client nutrition plan or personal workspace nutrition plan.	Authorized coach reads assigned targets and logs; client reads own plan and meal log; personal workspace owner reads own nutrition.	Coach manages targets and plans; client logs meals and swap requests; personal workspace owner manages own plan.	Allergy or restriction conflicts block publish; no unrelated coach edits; no support/admin default access.	Audit support/admin inspection, export, plan correction, or blocked-publish override review.
Messages, voice notes, attachments	Active coach-client relationship thread.	Relationship participants read thread content; ended relationships remain read-only for retained history.	Relationship participants send messages and attachments while the relationship is active.	No cross-thread browsing, no default support playback/download, no posting after relationship end.	Audit playback, download, export, or exceptional support/admin inspection.
Progress photos and media	Client-owned progress record inside an authorized relationship or personal workspace.	Client reads own media; authorized coach reads assigned client media; personal workspace owner reads own media through protected URLs.	Client uploads and manages own media; coach may annotate or request updates without replacing originals.	No long-lived signed URLs in cache, no broad media browsing, no cross-context reuse.	Audit support/admin access, download, export, redaction, or deletion workflows.
Risk flags, task inbox, priority summaries	Coach operational workspace scoped to authorized relationships.	Assigned coach and workspace owner read operational summaries for their active clients.	System and authorized coach actions update task state, triage, and follow-up status.	Clients do not see internal risk scoring in Public V1; no personal workspace spillover; no staff/admin default read.	Audit support/admin inspection, task reassignment, or incident escalation access.
Minimized operational telemetry	Platform operational context with Roles-approved internal scope.	Named production developers may search requestId, correlationId, eventId, jobId, clientOperationId, deviceId, receiptId, internal userId, workspaceId, and relationshipId when present in allow-listed minimized telemetry.	Systems append allow-listed telemetry; developers have read-only access.	No product payload/content, raw receipts, rejected-operation payloads, audit payloads, or direct product-record access. Searching an identifier in minimized telemetry does not grant access to the corresponding raw receipt, payload, diagnostic record, or product record.	Provider access/activity evidence follows the approved production telemetry context.
Sync receipts and diagnostics	User device/session record with restricted support/admin diagnostic scope.	User sees sync status only; support/admin reads raw receipts or diagnostics only through explicit audited grant.	System writes receipts and rejected operations; user can retry from product surfaces without editing raw payloads.	No raw payload browsing by product users, no cross-user diagnostics sharing, no silent admin mutation.	Audit every raw diagnostic read, receipt export, or support/admin action on rejected operations.
Audit logs	Platform-controlled compliance record retained by policy.	No direct product-user reads; approved support/admin operators read scoped logs for a named case.	System appends audit events; retention and legal workflows manage policy-bound redaction or export.	No coach/client browsing, no mutable history, no unscoped admin search across unrelated cases.	Audit log access itself must be logged with operator, reason code, scope, and retention reference.

Support/Admin Access

Support/admin authority is exceptional. It is never inherited from normal product roles.

Required Grant Shape

• No default product access.
• Explicit permission grant.
• Reason code required.
• Target resource scope required.
• Audit event required before sensitive read, write, playback, download, export, delete, redaction, or diagnostic inspection.

Telemetry Lookup Is Not Authorization

Routine minimized telemetry uses the Production Developer context. Following an identifier into a raw receipt, payload, product record, media object, repair, replay, or mutation requires a target-scoped, reason-coded, time-limited, audited support/admin grant.

Mutation Boundary

• Interactive support/admin grants are time-limited.
• Batch, legal, export, delete, and incident workflows record a case id plus expiry or review date.
• Support/admin cannot silently mutate user-owned health, nutrition, performance, message, or progress values.
• Redaction, export, delete, retention, and anonymization defer to privacy-and-retention.

Mobile And Offline Cache Boundaries

Permissions still apply after data is downloaded. Offline actions remain provisional until server authorization accepts them.

Cache Scope

• Mobile caches must be scoped by user, device, app surface, workspace, relationship, or personal workspace.
• Coached-client cache and personal workspace cache must remain separate even for the same user account.
• Signed media URLs must not be cached longer than expiration.
• Raw support diagnostics and rejected sync payloads must not be available in normal mobile UI caches.

Invalidation And Rejection

• Relationship end, permission revocation, logout, account deletion, workspace suspension, and device reset must trigger cache invalidation or protected purge behavior.
• A revoked device loses sync in both directions: push and pull are refused until the app registers again. A user may revoke only devices registered to their own account.
• Offline queued operations remain pending until server authorization accepts them.
• A local queued action that was permitted when created can still be rejected later if the server-side relationship, workspace, or data state changed.

Required Access Tests

Every feature must prove negative access paths, not only the happy path.

Context And Lifecycle Failures

• Wrong workspace.
• Wrong relationship.
• Wrong operating context.
• Wrong app surface.
• Inactive invitation.
• Paused relationship restrictions.
• Ended relationship write attempt.
• Deleted or anonymized relationship normal access attempt.

Support, Personal, Mobile, And Worker Failures

• Support/admin access without grant.
• Support/admin access without reason code.
• Personal workspace attempting to read coached-client records.
• Coached-client attempting to read personal workspace records.
• Dual-context user attempting to merge permissions.
• Mobile cache after relationship end, permission revocation, logout, or deletion.
• Revoked or unregistered device attempting sync push or pull.
• Worker attempting to process an event or sync operation without accepted authority.
• Unnamed or non-MFA production telemetry access.
• Using an approved telemetry identifier to fetch product data.
• Raw receipt or payload inspection without a support/admin grant.
• Replay, repair, or mutation through read-only telemetry access.

Related Authority Docs

Roles and permissions depend on lifecycle, privacy, API, sync, and release-gate decisions.

workflow-state-map

Defines the lifecycle states that gate access, editing, messaging, retention, and offboarding.

privacy-and-retention

Defines export, delete, anonymization, redaction, retention, and legal handling.

api-contract-standard

Defines authorization errors, contract conventions, idempotency, and generated-client boundaries.

offline-sync-protocol

Defines pending operations, sync receipts, conflicts, retries, and cache enforcement.

observability-plan

Defines minimized telemetry context needs, approved identifier search, and the boundary between read-only diagnosis and sensitive recovery.

Test And Release Gate

Defines the required evidence for access tests before Public V1 launch.