Platform Concepts

Understand how Aether is structured and how to work with its core concepts.

Overview

Aether is built on a workspace-based multi-tenant architecture. This means:

• Each Account (your identity) can access multiple Workspaces (your businesses/brands)
• Each Workspace operates independently with its own data, subscription, and team members
• Data is completely isolated between Workspaces - no cross-contamination

Core Entities

Account

Your personal identity in Aether. An Account:

• Has a single email address (used for authentication)
• Can own or be a member of multiple Workspaces
• Has a global profile with preferences

Workspace

A Workspace represents a business or brand. Each Workspace:

• Is the tenant root and aggregate root in our system
• Owns its Seats (team members)
• Has its own Subscription and Plan
• Contains all product-domain data (Ingredients, Vessels, Mixtures, Templates, Products, etc.)
• Has a status (Active, Suspended, Delinquent, etc.)

Seat

A Seat represents a user’s access to a Workspace. Each Seat:

• Belongs to one Account and one Workspace
• Has a Role (Owner, Admin, Member)
• Has a Status (Active, Pending, Revoked)
• Can be transferred between Accounts (for succession planning)

Role Permissions

Plans & Pricing

Aether offers three plans, with Enterprise including additional features:

Plan Limits

See Pricing Page for complete details.

Workspace Binding

When you authenticate with Aether, you specify which Workspace you want to work in using the X-Aether-Workspace header (prefixed with ws_<uuid>).

• Your role is resolved server-side from your Seat - never trusted from the token
• You can switch Workspaces by changing the header value
• You can only access Workspaces where you have an Active Seat

Authentication Flow

Aether’s auth core is identity-provider-agnostic (pure OAuth2/OIDC/JWKS; Zitadel for local/self-hosted deployments, WorkOS for managed cloud) with multiple authentication methods:

1. Magic Link - Passwordless login via email
2. OAuth - Google and other providers
3. SSO - SAML/OIDC for Enterprise plans

The authentication flow:

1. Login via magic link or OAuth
2. Receive JWT access token
3. Include token in Authorization header
4. Specify Workspace in X-Aether-Workspace header
5. Server validates token and resolves your Seat
6. Request proceeds with your permissions

Data Isolation

Aether enforces strict multi-tenant isolation:

• All product-domain tables include a workspace_id column
• Every Repository query automatically filters by the current Workspace
• Cross-workspace data access is never allowed through the workspace service
• Cross-workspace operations exist only in the separate Backoffice bounded context

This means you can safely:

• Run multiple brands under one Account
• Give team members access to specific Workspaces only
• Ensure no data leakage between businesses

Session Management

• Sessions are JWT-based with configurable expiration
• Session tokens can be revoked (logout)
• OAuth flows use PKCE for security
• Magic link tokens are single-use and time-limited

Audit Log

Enterprise plans include comprehensive audit logging:

• Lifecycle events - Workspace creation, deletion, status changes
• Product-domain mutations - All changes to Ingredients, Mixtures, Products, etc.
• Compliance reads - Access to SDS, allergen sheets, and other compliance documents
• Backoffice actions - Operator actions with reason fields and impersonation tracking

Audit logs are:

• Retained for plan-specific periods (Free: 30d, Entrepreneur: 1y, Enterprise: 7y)
• Hash-chained for tamper detection
• Accessible only to Workspace Owners/Admins (Entrepreneur/Enterprise)

Next Steps

• Learn about Product Development
• Understand Compliance Features
• View Pricing Details