Skip to content

Auth orgs admin

Generated from openspec/specs/auth-orgs-admin/spec.md — edit that file, not this page.

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.

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.

  • 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.

  • WHEN a user with an unverified email submits correct credentials to sign in
  • THEN the request is rejected with an EMAIL_NOT_VERIFIED error 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.com is 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
  • WHEN a signup on example.com is 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.

  • 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
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.

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
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.

  • WHEN a signed-in user with platform role admin requests an admin-only route or page
  • THEN the request succeeds and the admin UI/API surface is returned
  • WHEN a signed-in user whose platform role is not admin requests 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 sales requests 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 sales requests 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 admin sets another user’s role to sales (or back to user) 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.

  • WHEN the designated owner email address completes sign-up in the production environment
  • THEN that account’s platform role is admin from 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