Operator access groups and workflows

Start at Operator sign-in, choose Continue with Cognito · Role-based access, and complete the operator's existing two-factor check. The Access & workflows page shows your identity, groups, assignments, handbook and available fleets.

Roles and default permissions

Cognito group	What it can do	Assignment required
Operators	View assigned fleet, inventory, sales and reports; update machine name/notes/time zone and inventory	Explicit operator accounts
Zip_Operators	Same operational capabilities, constrained to assigned US ZIPs	Explicit operator accounts and five-digit ZIP codes
State_Operators	Same operational capabilities, constrained to assigned US states	Explicit operator accounts and ISO subdivision codes such as US-TX
Super_Admins	Platform administration, group creation and protected role assignment	Existing super administrator must grant this group
Hosts	View machine and inventory information; no changes or financial records	Explicit operator accounts and machine numbers
Contractors	View assigned machine and inventory information; submit machine restocks	Explicit operator accounts and machine numbers
Read-only	View permitted fleet, inventory, sales and reports; no writes	Explicit operator accounts

AWS group names cannot contain spaces. The portal displays “Zip Operators” and “State Operators”; their AWS identifiers use underscores. Custom groups created in the portal are organizational labels only: they confer no application permissions until a reviewed policy is implemented.

An admin, admins, Super_Admin or Super_Admins Cognito identity can manage ordinary groups. Only Super_Admin or Super_Admins can assign or modify super-administrator access. An administrator cannot change their own access through this page. Group management checks current AWS membership on each management request. A new group does not enroll a user or invent a fleet.

Set up an employee end to end

An existing administrator signs in with Cognito and completes operator MFA.
Open Access & workflows, then Assign an existing user.
Enter the existing Cognito username or supported email alias and select Find user.
Confirm the identity. The AWS user must be enabled and its email verified.
Select the role. Enter existing operator account emails; add the required ZIPs, states or machine numbers. Do not infer ownership from a matching email.
Review the assignment and save. The server changes only the managed role groups, records the immutable Cognito subject and a revision history, and refuses a save if another administrator changed the record first.
The employee performs a fresh Cognito sign-in and completes MFA.
Open Access & workflows, choose an available assigned fleet, then open Machines. Confirm the expected machines, try an out-of-scope request, and verify that an unauthorized write is refused.
To revoke access, load the user, clear Assignment active, and save. Explicit inactive assignments block managed access, including old role claims. AWS account/group changes made outside this flow take effect at token expiry, at most 15 minutes; group administration is rechecked live.

Never send passwords, recovery codes, tokens, tax identifiers or bank details in employee notes or access descriptions.

Territory and location boundaries

The existing operational API reports complete operator accounts. It does not produce geographically filtered financial totals. To prevent partial totals or exposure outside a territory, every machine in a selected operator account must fit the assignment. ZIP/state roles use machine country, postcode and subdivision; missing address data does not qualify. Hosts and contractors must be assigned every machine in the selected account.

A mixed-territory account is marked unavailable. Split its fleets into correctly owned operator accounts using the approved transfer process before granting territory access. Do not solve an unavailable fleet by granting administrator rights. New out-of-territory machines or a changed placement can make a fleet unavailable again. This release does not claim partial-account geographic filtering, per-machine financial reports, or automated transfers.

Workflow map

Flow	Steps and completion evidence	Role boundary
Identity and MFA	Cognito credentials/federation → operator authenticator enrollment or challenge → staff session → assigned fleet	All configured roles; no fleet data before MFA
Group management	View groups → create organizational group → visible in AWS-backed list	Cognito administrators; custom names grant no permissions
User assignment	Find verified user → role and scope → save revision → fresh user sign-in	Admins; super-admin grants require an existing super admin
Fleet registration and placement	Administrator or Operator registration → verified address → setup readiness → live device evidence	Operators can register/place machines; territory roles edit name/notes/time zone and inventory only; existing checks still apply
Inventory	Machine aisles → products and stock → restock → saved quantities and history	Operators/territory roles; contractors only the machine-restock endpoint
Service inspection	Assigned machines → health and inventory → diagnose → authorized restock → verify machine result	Hosts view; contractors restock; no remote dispense/unlock/reboot authority
Sales and reports	Select a complete assigned fleet → inspect records → reconcile payment and vend evidence	Operators, territory roles and Read-only; Hosts/Contractors do not read money
Refunds and payouts	Review the case → verify payment/vend evidence → approved financial process → processor confirmation	Financial mutations remain administrator-only; a note or approval is not payment
Remote device control	Inspect machine → authorized command → device acknowledgment → actual result	Administrator-only under the new role defaults; no command is sent by role setup
Teams and credentials	Review existing crew model → authorized administrator manages delegation/credentials	Crew roles are separate; managed roles cannot export credentials or grant themselves access
Agents and automation	Read the workflow documentation → verify permissions and readiness → separately authorized activation	A Cognito role never activates an agent or authorizes email sending
Supplier sourcing	Admin Supplier Desk → provider evidence → application → actual supplier decision → catalog rights	Separate Medusa staff policy; ordinary operator/host/contractor groups do not grant staff access
Offboarding	Load assignment → deactivate → verify denied access → reconcile any external AWS changes	Administrator; no destructive employee-record deletion required

Troubleshooting and verification

Group missing: ask an administrator to assign a supported group, then sign in again. A customer Cognito account alone is insufficient.
Assignment pending: the group exists but no active subject-bound grant is saved. Inspect the user and assignment revision.
Fleet unavailable: check every machine's owner, country, ZIP/state and explicit machine list. Whole-account territory boundaries are intentional.
403 on an action: the action is outside the role. Read-only always denies mutation even if another managed group appears in the token.
401 after sign-in: finish MFA or restart expired Cognito sign-in. Tokens live for 15 minutes; no browser refresh token silently extends authorization.
Save conflict: reload the assignment and reconcile the latest revision.
AWS/storage failure: the assignment remains inactive; reconcile actual Cognito membership and the stored revision before retrying. Never report an unsuccessful group update as completed.

The release tests must cover RSA signature/issuer/audience/expiry, non-admin access denial, nonce and MFA matching, read-only writes, explicit tenant selection, out-of-territory fleets, stale assignment versions, super-admin delegation, disabled/unverified users, and durable assignment reload. A real administrator browser walkthrough requires an authorized user to complete Cognito and MFA; automated fixtures are not evidence of that live walkthrough.

AWS group-name requirements

Release configuration

The shared pool is us-east-1_ah4qbr3Qv. The dedicated web client is 3jvl1kfuj6mcsf6dslblv86ujs; its only callback is https://operator.kiosk-x.ai/api/session/cognito/callback. Set KIOSKX_COGNITO_OPERATOR_CLIENT_ID to this client on the web and API deployments. The API uses its existing service account and the pool-scoped policy in infra/cognito-access-policy.json. No user-creation, password-reset, IAM-role management or account-deletion permissions are granted.

Assignments and MFA confirmations use the existing durable fleet database under operator_access. Production refuses access if its authoritative storage is unavailable. Assignment writes are serialized across PostgreSQL replicas and retain history. Tokens and credentials are not stored in these records.