How your organisation’s data is protected

Every database query runs through a Prisma extension that switches the connection to a non-owner Postgres role and sets a per-request tenant identifier, so PostgreSQL row-level security policies — not just application code — decide which organization's rows a request can see.

The API stack defaults RLS_ENFORCEMENT to 'strict', but it is a deploy-time context flag, and the Auth stack deliberately runs it 'off' for Cognito triggers. A signed-in user with no organization (a fan) is mapped to the public scope, which runs as the BYPASSRLS role: such a caller has no tenant rows to be confined to, so what limits those reads is each handler's own WHERE clause — the caller's own user id, or an explicit resource id — rather than RLS. The case RLS exists for, an authenticated member of one organization reading another, still requires a tenant and stays fully enforced.

BallOBall ships a fixed set of roles — platform admin, platform support, league admin, coach, scorekeeper, referee, player, fan and a scan-only gate agent — and league admins can grant additional roles to members, including grants scoped to a single sport, league or team.

Roles are a fixed enum; organizations cannot define their own top-level roles. Sensitive listings (minors' ID documents, referee 1099 earnings, background-check results) require an organization-wide grant, because narrower club-scoped grants intentionally pass the coarse role check used for navigation gates — those endpoints call a separate tenant-wide guard that rejects a club-, league-, team- or sport-scoped grant.

Within a club, admins can create named roles with a chosen set of capabilities and assign members to them, and those capabilities gate club surfaces such as the club reports.

Custom roles exist only at the club level, not at the organization or league level, and they draw from a fixed capability list rather than arbitrary permissions.

Accounts are managed in Amazon Cognito, and new sign-ups must confirm their email address before the account is usable unless an operator explicitly enables auto-confirm.

Auto-confirm is a deploy flag that defaults to false; enabling it would skip verification. Cognito treats the email as a case-sensitive username.

Any signed-in user can turn on two-factor authentication with a standard authenticator app from their own security settings, and turn it off again.

TOTP only — no SMS and no hardware-key second factor. The user pool has MFA set to OPTIONAL, so 2FA is opt-in per user unless a platform operator turns on the platform-wide requirement. Enrollment is presented via a copyable secret and otpauth:// URI, not a rendered QR code — no QR library is a dependency, so the secret is typed or pasted into the authenticator app.

A saved security policy — maximum session age, an IP allowlist, and a requirement that all users enroll a second factor — is enforced by the API on every authenticated request.

This is a single platform-wide policy stored on one settings row and editable only by BallOBall platform staff (SUPER_ADMIN / PLATFORM_SUPPORT). Customer organizations cannot set their own session timeout, IP allowlist, or 2FA requirement. Of the three 2FA scopes, only ALL_USERS is enforced at the API — ROOT_ONLY and ALL_PLATFORM_ADMINS name exactly the two platform roles that bypass every check in this middleware, deliberately, so those two settings are saved but unenforced.

The production database is encrypted at rest with automated backups and deletion protection enabled, and uploaded files live in a versioned, encrypted bucket with all public access blocked.

AWS-managed encryption keys (S3-managed for objects, default RDS storage encryption) — there is no bring-your-own-key or customer-managed KMS option. Backup retention is configured at seven days. Everything runs in a single AWS region (us-east-2 by default), so there is no data-residency choice.

Every API request passes through a rate limiter that counts requests per organization and per client IP in a fixed one-minute window and returns a throttling response once the budget is exceeded.

A single shared default budget applies per organization-and-IP pair; it is not configurable per customer. A named set of hot scoring routes is explicitly exempted.

Administrative actions across the platform write audit records capturing the action, the actor, the target and a timestamp, browsable and filterable in a paginated console with a per-organization view.

Both the platform-wide and per-organization audit feeds are readable only by BallOBall platform staff (SUPER_ADMIN / PLATFORM_SUPPORT); there is no audit-log screen a customer's own admin can open. Writes are best-effort and fire after the mutation commits — if the audit insert fails it is logged to CloudWatch and the mutation still stands, so the trail is not a transactional guarantee.

A user can delete their own account from within the app, and a minor's data can be exported or erased by the player, a verified guardian, an organization admin or platform staff — deliberately not behind any feature toggle.

Self-deletion is refused for staff accounts and for anyone who still owns an organization; ownership must be transferred first. Whole-organization export and user anonymization are platform-staff actions, not self-serve.

Families and organization admins can store residency, medical, insurance and photo-ID documents against a household: the storage key is generated server-side and bound to the uploader with a signed token, the file is never given a public URL, and retrieval happens only through a short-lived signed link.

Access is limited to a guardian of that household, an admin of the household's organization, and platform staff. The underlying bucket uses S3-managed encryption with public access blocked; there is no customer-managed key option.

Guardians can be linked to and verified against a minor player, team messaging is checked against that policy before a message is stored, and admins get a review queue of policy violations they can resolve.

The policy currently LOGS violations rather than blocking them — the service's stated v1 contract always returns allowed, so no message is actually refused, and no notification is sent to the guardian when a violation fires. Hard-blocking is described in the code as v2 work behind a per-tenant flag that does not exist yet.