User Management¶

Available to: Owner (tenant-level management), Platform Admin (global management)

Users in Hardhat Flow are tenant-scoped. Each user belongs to exactly one tenant and has exactly one role. Authentication is handled by Auth0 — no passwords are stored in the application database.

User Fields¶

Field	Description
`email`	Unique within the tenant. Used for Auth0 login and correspondence.
`first_name`	User's first name.
`last_name`	User's last name.
`phone`	Mobile phone number. Required for SMS notification delivery.
`role`	The user's single assigned role. See roles below.
`avatar_url`	Optional profile photo URL.
`status`	`active` or `inactive`. Inactive users cannot log in.

Roles¶

Each user has exactly one role. Roles are not combinable.

Role	Description
Platform Admin	Operates the platform. Not a tenant user.
Owner	Full control over their tenant: approvals, user management, all data.
Accounting	Financial view: invoices, payments, bid prices. Cannot manage jobs.
Project Manager	Creates and manages bids and jobs within their assignments.
Supervisor	Field-level visibility and updates on assigned jobs.
Badge Worker	Limited view of assigned jobs only. No management capabilities.

Role changes are recorded in the ActivityLog under role_change. Choose roles carefully — they govern all data access and API permissions.

Initial Owner Provisioning¶

When a Platform Admin approves a tenant's AccessRequest, the application automatically creates the first user inside the new tenant database and sends an invite email:

The signup email becomes the first Owner of the tenant.
The Owner row is written with role owner and status=active.
The backend creates an Auth0 user account for the Owner's email and sends a welcome email from Hardhat Flow with a secure link to set their password.
The Owner clicks the link, sets a password, and logs in. On first login, their Auth0 account is linked to the pre-provisioned row.

!!! note "If the welcome email fails to send (e.g., transient network error), the tenant is still provisioned and the Owner row is created. The Platform Admin can share the tenant login URL out-of-band; the Owner can still self-register with the same email address. An auth0_invite_failed entry is written to the ActivityLog so the failure is visible."

Platform Admin accounts (support staff who can act inside your tenant) do not appear on Settings → Team for Owners or other tenant roles. Only another Platform Admin acting in your tenant sees those rows. Platform Admins still manage those accounts from the platform admin console when needed.

Inviting Users¶

Owners invite new users to their tenant:

Owner navigates to Settings → Team → Invite User.
Enters the new user's full profile: email, first name, last name, phone, and role. Owners can assign Accounting, Project Manager, Supervisor, or Badge Worker — but not Owner or Platform Admin.
Hardhat Flow creates the user row in the tenant database with the chosen role, then immediately creates an Auth0 account and sends the invitee a welcome email explaining who invited them, which company they are joining, and a secure link to set their password.
The invitee receives the email, clicks the link, sets a password, and logs in — they land directly in the tenant with their assigned role.

!!! tip "The welcome email is sent from Hardhat Flow (not a generic Auth0 password reset). It includes who invited them, the company name, and clear next steps for signing in."

!!! note "If the welcome email fails, the user row is still created and the API response includes a _warning field. The invitee can still sign up at the login page with the same email address and will be linked automatically on first login."

!!! note "Invitations do not expire. A pre-provisioned row stays valid until the Owner deletes it or the invitee logs in for the first time."

Role precedence¶

For tenant users (Owner, Accounting, Project Manager, Supervisor, Badge Worker), the local database role assigned by the Owner is authoritative across logins. JWT role claims for tenant users are ignored, so an Owner-managed role assignment survives subsequent logins regardless of what Auth0 carries on the token. Only the Platform Admin role is sourced from the Auth0 JWT.

Access Request Flow¶

Prospective customers submit an access request through the public landing page; they do not yet have an Auth0 account:

The prospective customer visits the marketing site and submits the access-request form (company name, contact name, email, phone).
A Platform Admin reviews pending requests at Platform Admin → Access Requests.
On approval, the platform provisions a new tenant database, runs migrations, creates the Owner user inside it, and automatically sends the Owner a welcome email with a password-set link (see Initial Owner Provisioning above).
The Owner clicks the link in the email, sets a password, and logs in immediately — no separate link-sharing step needed.

Auth0 Integration¶

Hardhat Flow uses Auth0 for all authentication. Key implications:

No passwords are stored in the application database. Credentials live entirely in Auth0.
Login tokens are JWTs issued by Auth0 and validated by the application on each request.
Password resets, social login, and multi-factor authentication are all managed through Auth0.
The application user record is synced from Auth0 on login (email, name, avatar).

MFA Requirements¶

Multi-factor authentication is enforced for two roles:

Owner — required on every login.
Platform Admin — required on every login.

All other roles may optionally enable MFA through their Auth0 account settings, but it is not mandated.

MFA enforcement is configured at the Auth0 tenant level. Disabling it for Owner or Platform Admin requires Auth0 admin access and is strongly discouraged.

Activating and Deactivating Users¶

Owners can deactivate any non-Owner user in their tenant from the Team page:

Toggling Active → Inactive sets is_active=false on the local user record and prevents the API from accepting requests on their behalf.
Owners can also remove a non-Owner user via the trash icon — this performs a soft-delete (is_deleted=true); the row is preserved for audit but the user no longer appears in the Team list.
Owners cannot deactivate, demote, or remove themselves; the Owner role is managed by Platform Admin.
Deactivated users retain all their historical records, assignments, and ActivityLog entries. Reactivation restores access.

!!! warning "Owner accounts are protected from in-tenant edits. To change an Owner — for example after a contact change — a Platform Admin must update the row from the Platform Admin → Tenants → Users view."

Phone Number and SMS¶

The phone field on a user record is required for SMS notification delivery.

Without a phone number, any SMS notifications targeting that user will be silently skipped.
A warning is logged each time a notification cannot be delivered due to a missing phone.
Owners should ensure that all PM, Supervisor, and Owner accounts have a valid phone number on file.

Collect phone numbers during onboarding to ensure no notifications are missed from day one.