Auth orgs admin
Generated from
openspec/specs/auth-orgs-admin/spec.md— edit that file, not this page.
Purpose
Section titled “Purpose”Authentication, multi-tenancy, and platform administration for Tinkerspace. Every signed-up user is authenticated by email + password with mandatory email verification, is auto-provisioned a personal organization to scope their data, and may hold one of two elevated platform roles (admin super-admin, sales invoice-only) layered on top of per-organization membership roles.
Requirements
Section titled “Requirements”Requirement: Email/password sign-up with mandatory OTP verification
Section titled “Requirement: Email/password sign-up with mandatory OTP verification”The system SHALL require email + password for account creation, SHALL send a 6-digit one-time code to the email address on sign-up, and SHALL NOT consider the account verified until that code is confirmed.
Scenario: OTP sent on sign-up
Section titled “Scenario: OTP sent on sign-up”- WHEN a new user completes the sign-up form with email + password
- THEN a 6-digit code is emailed to that address, valid for 10 minutes, and the web app walks the user through code entry before treating them as verified
Scenario: Verifying the code signs the user in
Section titled “Scenario: Verifying the code signs the user in”- WHEN the user submits the correct 6-digit code before it expires
- THEN the account is marked verified and the user is automatically signed in without re-entering credentials
Requirement: Sign-in blocked until email is verified
Section titled “Requirement: Sign-in blocked until email is verified”The system SHALL reject sign-in attempts for an unverified account rather than issuing a session.
Scenario: Unverified sign-in is rejected
Section titled “Scenario: Unverified sign-in is rejected”- WHEN a user with an unverified email submits correct credentials to sign in
- THEN the request is rejected with an
EMAIL_NOT_VERIFIEDerror instead of a session, and the web UI routes the user to OTP entry
Requirement: Disposable test accounts are pre-verified outside production
Section titled “Requirement: Disposable test accounts are pre-verified outside production”The system SHALL create accounts on the reserved example.com domain already email-verified in every environment except production, so automated suites can obtain a session, and SHALL NOT apply this to any other domain or to production.
Scenario: A fixture account can sign in on dev
Section titled “Scenario: A fixture account can sign in on dev”- WHEN a signup on
example.comis submitted to a non-production environment - THEN the account is stored with its email already verified, and a subsequent sign-in issues a session rather than
EMAIL_NOT_VERIFIED
Scenario: Production never pre-verifies
Section titled “Scenario: Production never pre-verifies”- WHEN a signup on
example.comis submitted to production - THEN the account is stored unverified and follows the ordinary OTP flow
Scenario: Only the exact reserved domain qualifies
Section titled “Scenario: Only the exact reserved domain qualifies”- WHEN a signup uses an address that merely resembles the fixture domain, such as a subdomain or a longer domain that begins with it
- THEN it is stored unverified, in every environment
Requirement: Personal organization auto-provisioning
Section titled “Requirement: Personal organization auto-provisioning”The system SHALL create a personal organization and an owner membership for that organization automatically whenever a new user account is created, so every user has an organization scope from their first session.
Scenario: New signup gets a personal org
Section titled “Scenario: New signup gets a personal org”- WHEN a user account is created (sign-up completes)
- THEN a new organization is created with a name derived from the user’s name or email, the user is added to it as
owner, and the organization is marked as personal (distinguishable from team organizations invited into later)
Requirement: Active-organization scoping for org-scoped data
Section titled “Requirement: Active-organization scoping for org-scoped data”The system SHALL scope organization-dependent data (catalog assets, projects, credits, etc.) to the session’s active organization, and SHALL treat a session with no active organization as having no org context rather than defaulting to one.
Scenario: Fresh session has no active organization
Section titled “Scenario: Fresh session has no active organization”- WHEN a user signs in for the first time in a session (before selecting an organization)
- THEN the session’s active-organization field is null, and any handler reading org-scoped data must treat that as “no org context” rather than assuming a default organization
Scenario: Selecting an organization scopes subsequent requests
Section titled “Scenario: Selecting an organization scopes subsequent requests”- WHEN the user selects an organization in the org switcher
- THEN the session’s active organization is set to that organization, and subsequent org-scoped reads/writes are filtered to it
Requirement: Organization invitations for team membership
Section titled “Requirement: Organization invitations for team membership”The system SHALL allow an existing organization member to invite a new member by email, and SHALL grant that membership only once the invited person accepts.
Scenario: Invited user accepts and joins the organization
Section titled “Scenario: Invited user accepts and joins the organization”- WHEN a person receives an organization invitation email and opens its accept link, then signs in or signs up
- THEN they become a member of that organization with the role specified in the invitation
Requirement: Project share-link invitations independent of org invitations
Section titled “Requirement: Project share-link invitations independent of org invitations”The system SHALL support inviting a person to a single project via a one-time shareable link, as a mechanism distinct from organization invitations, and SHALL make each link usable exactly once.
Scenario: Share link grants project access on first use
Section titled “Scenario: Share link grants project access on first use”- WHEN a recipient opens a valid, unused project share link and signs in
- THEN they are added as a project member, and the link is marked used
Scenario: Reused or expired share link is rejected
Section titled “Scenario: Reused or expired share link is rejected”- WHEN a recipient opens a project share link that has already been accepted, or that has expired
- THEN the accept request is rejected (already-accepted vs. expired are distinguishable outcomes) rather than granting access again
Requirement: Platform admin role unlocks the full admin surface
Section titled “Requirement: Platform admin role unlocks the full admin surface”The system SHALL grant a user whose platform role is admin access to the complete administrative surface (user list/ban/impersonation, batch imports, vendor review, credit grants, sales invoices), and SHALL deny that surface to any user without the admin role.
Scenario: Admin user reaches admin routes
Section titled “Scenario: Admin user reaches admin routes”- WHEN a signed-in user with platform role
adminrequests an admin-only route or page - THEN the request succeeds and the admin UI/API surface is returned
Scenario: Non-admin user is denied
Section titled “Scenario: Non-admin user is denied”- WHEN a signed-in user whose platform role is not
adminrequests an admin-only route - THEN the request is rejected (403) regardless of their organization membership role
Requirement: Sales role grants invoice access only
Section titled “Requirement: Sales role grants invoice access only”The system SHALL grant a user whose platform role is sales access to exactly the sales-invoice surface, and SHALL deny that user every other admin-only route, page, and navigation entry.
Scenario: Sales user can generate invoices
Section titled “Scenario: Sales user can generate invoices”- WHEN a signed-in user with platform role
salesrequests the invoice page or an invoice-generation endpoint - THEN the request succeeds
Scenario: Sales user is denied other admin surfaces
Section titled “Scenario: Sales user is denied other admin surfaces”- WHEN a signed-in user with platform role
salesrequests an admin-only route or page other than the invoice surface (e.g. user management, batch imports) - THEN the request is rejected (403), and the navigation UI does not present a link to it
Scenario: Admin can assign or remove the sales role
Section titled “Scenario: Admin can assign or remove the sales role”- WHEN a user with platform role
adminsets another user’s role tosales(or back touser) via the admin user-management UI - THEN that user’s invoice access changes accordingly on their next request, with no other permission system involved
Requirement: Owner account auto-promoted to admin in production
Section titled “Requirement: Owner account auto-promoted to admin in production”The system SHALL automatically grant the platform-owner’s account the admin role at sign-up time in the production environment, without a manual step.
Scenario: Owner signs up in production
Section titled “Scenario: Owner signs up in production”- WHEN the designated owner email address completes sign-up in the production environment
- THEN that account’s platform role is
adminfrom its very first session
Requirement: Bearer-token authentication for non-browser clients
Section titled “Requirement: Bearer-token authentication for non-browser clients”The system SHALL issue a bearer token to non-browser clients on sign-in, and SHALL accept that token as an alternative to the session cookie on subsequent requests.
Scenario: Script authenticates without cookies
Section titled “Scenario: Script authenticates without cookies”- WHEN a non-browser client (e.g. an automated test or script) signs in
- THEN it receives a bearer token in the response, and can authenticate later requests by sending
Authorization: Bearer <token>instead of a cookie