Design Philosophy

The SC Platform's security model follows three core principles:

• Fail closed — No scope assignment means no data. No tenant means no access. No exceptions, no fallbacks, no dev overrides in any environment.
• Scope at the boundary, not in the UI — Access control is enforced at the API and database query level, never just hidden in the frontend. A disabled button in the UI is a convenience; the real guard is the server rejecting the request.
• Same model for humans and agents — When the AI Engine runs a tool on behalf of a user, it inherits that user's exact scopes. An AI agent never has more access than the person who triggered it.

Authentication — Who Are You?

The platform supports exactly two authentication methods. There is no third option, no fallback, and no exception.

Entra ID (Humans)

All human users authenticate via Microsoft Entra ID (Azure AD) using PKCE-based OAuth 2.0. This applies to every tool in the ecosystem — Ask Ricky, Pennywise, Hawkeye, Ops Dashboard, Platform Admin.

• Browser-based PKCE flow — no client secrets exposed to the frontend
• Bearer JWT token sent with every API request
• Token identifies the person; a database User row maps them to tenant + role
• No API keys for humans — ever
• No dev/test bypass in any environment

API Keys (Machines)

Machine-to-machine callers (agents, connectors, external integrations) use sk_-prefixed API keys.

• Opaque bearer token, hash-matched to an ApiKey row in the database
• Each key is bound to a specific tenant
• Scopes are stored as ApiKeyScope rows — each key can only do what its scopes allow
• Keys are created and managed through Platform Admin
• Revocation is immediate

Property	Entra ID (Humans)	API Keys (Machines)
Token type	JWT (signed by Microsoft)	Opaque sk_ string
Identity binding	User row (Entra OID → tenant + role)	ApiKey row (hash → tenant + scopes)
Scope source	User's group/role membership	ApiKeyScope rows on the key
Management	Entra ID / Azure Portal	Platform Admin
Revocation	Entra token expiry + revocation	Delete key in Platform Admin

Multi-Tenant Isolation

Every domain table in the platform has a tenantId column. Every database query filters by it. This is the foundational security boundary:

• A user in Tenant A cannot see, query, or infer the existence of data in Tenant B
• Queries that don't filter by tenant are treated as bugs — enforced by code review and linting
• Per-tenant configuration controls which integrations are active (which M-Link endpoints, which Samsara fleet, etc.)
• Integration credentials (API keys, OAuth tokens for external systems) are stored per-tenant
• Every service method takes ctx: { tenantId, principal, logger } as its first argument — tenant isolation is structural, not optional

Role Hierarchy

Users are assigned a role that determines their feature-level access. The hierarchy is strictly ordered:

Role	Access Level	Typical User
MEMBER	Standard data access within their scoped boundaries. Can use tools, submit feedback, view data they're authorized to see.	Mechanics, area managers, analysts
TENANT_ADMIN	Everything a MEMBER can do, plus tenant configuration: manage users, configure integrations, manage API keys within their tenant.	IT leads, department heads
SUPER_ADMIN	Cross-tenant access. Can create tenants, manage the platform itself, configure global settings.	Platform development team

Each API route declares exactly one guard — requireMember, requireTenantAdmin, or requireSuperAdmin. There is no "check both" ambiguity.

Scope System

Scopes are the fine-grained permissions that control what data a caller can access. Unlike roles (which are about feature access), scopes are about data access — specifically, which categories of data a caller can read or act on.

Scope Catalog

Scope	What It Gates	Used By
Agent.Run	Permission to start an AI agent conversation at all	Ask Ricky
Telemetry.Read	Live sensor data, fault codes, alarms from M-Link / Enbase	Ask Ricky, Ops Dashboard
Assets.Read	Equipment profiles — unit makeup, specs, configuration	Ask Ricky, Ops Dashboard
WorkHistory.Read	Past maintenance records, corrective maintenance items	Ask Ricky
KnowledgeBase.Read	Curated troubleshooting guides and general knowledge	Ask Ricky
Directory.Read	Employee/mechanic directory for dispatch lookup	Ask Ricky
FleetLocation.Read	Real-time vehicle GPS positions from Samsara	Ops Dashboard
KnowledgeBase.Write	Create and modify knowledge base articles	Ricky Curator
Tenant.Admin	Tenant configuration, user management, API key management	Platform Admin

How Scopes Are Assigned

• For humans: Scopes are determined by the user's group membership and role configuration in the platform. Managed through Platform Admin.
• For API keys: Scopes are explicitly attached as ApiKeyScope rows when the key is created. A key with only Telemetry.Read cannot access work orders, regardless of what code calls it.
• For AI agents: The agent inherits scopes from the caller who triggered it (see AI Tool Gating below).

AI Tool Gating

This is where the platform's permission model becomes uniquely powerful. When the AI Engine receives a request from Ask Ricky:

• The agent's available tools are dynamically composed based on the caller's scope profile
• If a user doesn't have Telemetry.Read, the "Get Telemetry" tool doesn't exist for that agent session — Claude can't even try to call it
• If the user has the scope but asks about a unit outside their data boundary, the tool returns no data — not an error, just empty results
• The agent's system instructions are also composed dynamically — it's told what it can and cannot do based on the caller's profile
• This same mechanism will power proactive agents — a background agent running as "Permian Basin Area Monitor" gets exactly the scopes configured for that identity

Row-Level Access Control

Beyond scopes (which gate categories of data), some tools enforce row-level filtering based on the user's organizational assignment.

Pennywise RBAC

Pennywise has the strictest row-level controls in the ecosystem because it handles sensitive financial data:

• Every user has a scope assignment — a set of regions, areas, or specific units they can see
• Every database query filters by these assignments at the SQL level — not in the UI, not in middleware
• A West region manager cannot see East or South data, period
• No scope assignment = no data returned (tested with "no backdoor" assertions)
• Scope assignments are managed by admin users through Pennywise's built-in admin panel

Hawkeye Org-Based Visibility

Hawkeye uses the org chart to determine what approval items a manager sees:

• Managers see only their direct and indirect reports' approval items
• The org chart (maintained in Hawkeye's org chart editor) defines the chain of authority
• Approval routing follows this chain — items escalate up the tree
• This same org structure will route proactive agent alerts to the right person

Per-Tool Auth Patterns

Tool	Auth Method	Scope Model	Data Filtering
Ask Ricky	Entra ID (PKCE)	Platform scopes → AI tool gating	Per-unit data access via scopes
Pennywise	Entra ID (PKCE)	Role + scope assignment	Row-level RBAC (region/area/unit)
Hawkeye	Entra ID (PKCE)	Org chart-based visibility	Reports chain filtering
Ops Dashboard	Entra ID (PKCE)	Platform scopes	Scope-filtered API responses
TrueCount	Entra ID (PKCE)	Platform scopes	Warehouse assignment
Platform Admin	Entra ID (PKCE)	TENANT_ADMIN / SUPER_ADMIN role	Tenant-scoped management
AI Engine	Inherits from caller	Caller's scopes → tool composition	Tool-level + data-level filtering

Audit & Logging

• Every API request is logged with: caller identity, tenant, endpoint, timestamp, response code
• AI agent tool invocations are tracked — which tools were called, what data was accessed
• Hawkeye approval decisions include a full audit trail: who decided, when, what version of the data they saw
• Pennywise allocation runs are immutable once locked — CANONICAL runs cannot be modified, only restated through governed RESTATEMENT runs
• API key usage is tracked for monitoring and anomaly detection

Administration

The permission model is managed through two primary interfaces:

Related