Organization & Domain Verification Policy

Document ID: PLCY-ORG-001
Version: 1.0
Effective Date: December 22, 2025
Last Review: December 22, 2025
Owner: Hop And Haul Team

---

CONFIDENTIAL

This document is CONFIDENTIAL and for internal use only. Do not distribute outside the organization.

1. Purpose

This document establishes the policies and procedures for organization onboarding, domain verification, and multi-tenant user registration within the Hop And Haul platform.

---

2. Scope

This policy applies to:

• Organization account creation and management
• Email domain verification for user self-registration
• Multi-domain configurations
• User provisioning and access control
• Tenant data isolation

---

3. Multi-Tenant Architecture

3.1 Tenant Model

Concept	Description
Organization	Top-level tenant entity (company, fleet operator)
Domain	Verified email domain linked to organization
User	Individual account, belongs to one organization
Role	Permission set assigned to user within organization

3.2 Data Isolation

Isolation Level	Implementation
Database	All tables include org_id foreign key
Queries	Application enforces org_id filter on all queries
API	JWT contains org_id claim, validated on every request
Audit	All audit logs tagged with org_id

3.3 Database Schema

-- Organizations table
CREATE TABLE organizations (
    id UUID PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    status VARCHAR(50) NOT NULL DEFAULT 'active',
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    settings JSONB
);

-- Verified domains table
CREATE TABLE organization_domains (
    id UUID PRIMARY KEY,
    org_id UUID NOT NULL REFERENCES organizations(id),
    domain VARCHAR(255) NOT NULL UNIQUE,
    verification_status VARCHAR(50) NOT NULL DEFAULT 'pending',
    verification_method VARCHAR(50),
    verified_at TIMESTAMP,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- Users table
CREATE TABLE users (
    id UUID PRIMARY KEY,
    org_id UUID NOT NULL REFERENCES organizations(id),
    email VARCHAR(255) NOT NULL UNIQUE,
    role VARCHAR(50) NOT NULL,
    status VARCHAR(50) NOT NULL DEFAULT 'active',
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

---

4. Organization Onboarding

4.1 Onboarding Process

Step	Action	Owner	Requirements
1	Business inquiry received	Sales	Company name, contact info
2	Contract and terms executed	Legal	Signed agreement
3	Organization record created	Operations	Unique org name
4	Admin user provisioned	Operations	Verified admin email
5	Primary domain submitted	Org Admin	Domain ownership
6	Domain verification completed	System	See Section 5
7	Additional domains added (optional)	Org Admin	Verification per domain
8	User self-registration enabled	System	Verified domain(s)

4.2 Organization Settings

Setting	Default	Description
allow_self_registration	true	Users can register with verified domain email
require_email_verification	true	New users must verify email
default_user_role	driver	Role assigned to self-registered users
allowed_domains	[]	List of verified domains
max_users	1000	Maximum users per organization

---

5. Domain Verification

5.1 Verification Requirements

Requirement	Description
Domain ownership	Registrant must control the domain
Unique domain	Each domain can only be linked to one organization
Valid format	Must be valid domain (e.g., company.com)
No public domains	Cannot verify gmail.com, outlook.com, etc.

5.2 Blocked Public Domains

The following domains cannot be verified:

gmail.com, googlemail.com, outlook.com, hotmail.com,
live.com, msn.com, yahoo.com, ymail.com, aol.com,
icloud.com, me.com, mac.com, protonmail.com,
proton.me, zoho.com, mail.com, gmx.com, fastmail.com

5.3 Verification Methods

Method	Process	Verification Time
DNS TXT Record	Add TXT record with verification token	< 24 hours
Email to admin	Send verification link to admin@ or webmaster@	< 1 hour
Meta Tag	Add meta tag to website root	< 24 hours

5.4 DNS TXT Verification (Recommended)

Step	Action
1	System generates unique verification token
2	Org admin adds TXT record: fleetlink-verification=[token]
3	System polls DNS for verification (hourly for 72 hours)
4	On match, domain marked as verified
5	TXT record can be removed after verification

Example DNS Record:

Type: TXT
Host: @
Value: fleetlink-verification=a1b2c3d4e5f6g7h8i9j0

5.5 Verification Status

Status	Description
pending	Verification initiated, awaiting confirmation
verified	Domain ownership confirmed
failed	Verification unsuccessful after 72 hours
revoked	Domain verification revoked (ownership changed)

5.6 Re-verification

Trigger	Action
Domain transfer	Automatic re-verification required
Annual review	Optional periodic re-verification
Security incident	Manual re-verification initiated

---

6. Multi-Domain Support

6.1 Multiple Domains per Organization

Organizations may verify multiple email domains:

Use Case	Example
Primary domain	acmelogistics.com
Subsidiary	acmetransport.com
Regional	acme.co.uk, acme.de
Acquisition	formercompany.com

6.2 Domain Management

Action	Who Can Perform	Audit Logged
Add domain	Org Admin	Yes
Initiate verification	Org Admin	Yes
Remove domain	Org Admin	Yes
View domains	Org Admin, Operations	Yes

6.3 Domain Limits

Limit	Value	Rationale
Max domains per org	10	Prevent abuse
Min domains per org	1	At least one for registration
Concurrent verifications	3	Rate limiting

---

7. User Self-Registration

7.1 Registration Flow

User visits signup → Enters email → System checks domain →
Domain verified? → Yes → Send verification email →
User clicks link → Account created with default role

Step	Validation
Email entered	Valid email format
Domain check	Domain belongs to verified org
Duplicate check	Email not already registered
Email verification	User clicks verification link (expires 24 hours)
Account creation	User assigned to org, default role applied

7.2 Registration Constraints

Constraint	Enforcement
Verified domain required	Registration blocked for unverified domains
Email uniqueness	Global uniqueness across all organizations
Rate limiting	Max 10 registrations per domain per hour
Organization capacity	Registration blocked if org at max_users

7.3 Default Roles

Role	Permissions
driver	Create rides, update GPS, view own history
dispatcher	View all org rides, assign drivers
admin	Manage users, view reports, configure org
owner	Full org access, manage admins, billing

---

8. JWT Claims and Organization Context

8.1 JWT Payload Structure

{
  "sub": "user-uuid",
  "org_id": "org-uuid",
  "role": "driver",
  "email": "user@company.com",
  "iat": 1703203200,
  "exp": 1703289600
}

8.2 Authorization Flow

Step	Action
1	Request received with JWT
2	JWT signature validated
3	Expiration checked
4	org_id extracted from claims
5	All database queries filtered by org_id
6	Response contains only org-scoped data

8.3 Cross-Organization Access

Scenario	Allowed
User viewing own org data	Yes
User viewing other org data	No
Admin viewing own org data	Yes
Super-admin (Hop And Haul staff)	Yes, with audit

---

9. Organization Lifecycle

9.1 Status Transitions

From	To	Trigger
active	suspended	Non-payment, policy violation
suspended	active	Issue resolved
active	deactivated	Contract termination
deactivated	deleted	Data retention period expired

9.2 Suspension Effects

Component	Behavior When Suspended
User login	Blocked
API access	Blocked
Data	Preserved, not accessible
Billing	Paused or continued per contract

9.3 Deactivation and Data Retention

Data Type	Retention After Deactivation
User accounts	30 days, then anonymized
Ride history	Per PLCY-RET-001 retention schedule
Audit logs	Per PLCY-RET-001 retention schedule
Organization record	Retained for audit purposes

---

10. Security Controls

10.1 Domain Verification Security

Control	Implementation
Token entropy	256-bit random tokens
Token expiration	72 hours
Rate limiting	5 verification attempts per domain per day
Audit logging	All verification attempts logged

10.2 Cross-Tenant Protection

Attack Vector	Mitigation
Parameter tampering	org_id from JWT, not request
SQL injection	Parameterized queries, ORM
IDOR	org_id enforced at query level
Session hijacking	Stateless JWT, short expiration

10.3 Domain Takeover Prevention

Scenario	Protection
Domain expires	Re-verification required on transfer
Domain sold	New owner cannot inherit verification
Subdomain takeover	Only root domains verified

---

11. API Endpoints

11.1 Organization Management

Endpoint	Method	Description	Auth Required
/api/v1/organizations	POST	Create organization	Hop And Haul Admin
/api/v1/organizations/{id}	GET	Get organization details	Org Admin
/api/v1/organizations/{id}	PATCH	Update organization	Org Admin
/api/v1/organizations/{id}/domains	GET	List verified domains	Org Admin
/api/v1/organizations/{id}/domains	POST	Add domain	Org Admin
/api/v1/organizations/{id}/domains/{domain}	DELETE	Remove domain	Org Admin

11.2 Domain Verification

Endpoint	Method	Description	Auth Required
/api/v1/domains/verify/initiate	POST	Start verification	Org Admin
/api/v1/domains/verify/status	GET	Check verification status	Org Admin
/api/v1/domains/verify/confirm	POST	Manual confirmation (email method)	None (token)

11.3 User Registration

Endpoint	Method	Description	Auth Required
/api/v1/auth/register	POST	Self-register with verified domain	None
/api/v1/auth/verify-email	POST	Confirm email verification	None (token)

---

12. Audit Requirements

12.1 Logged Events

Event	Data Captured
Organization created	org_id, name, creator
Domain added	org_id, domain, added_by
Domain verified	org_id, domain, method, timestamp
Domain removed	org_id, domain, removed_by
User registered	org_id, user_id, email domain
User role changed	org_id, user_id, old_role, new_role, changed_by

12.2 Retention

See PLCY-RET-001 Records Retention Policy for audit log retention requirements.

---

13. Document References

Document	Relevance
PLCY-ACC-001 Access Control Matrix	Role definitions
PLCY-SEC-001 Security Controls	Authentication requirements
PLCY-RET-001 Records Retention	Data retention requirements
PLCY-DATA-001 Data Classification	PII handling

---

14. Revision History

Version	Date	Author	Changes
1.0	December 22, 2025	Operations Director	Initial release