Concepts & Architecture

System Overview

┌─────────────────────────────────────────────────────────────┐
│                     VYNTECH ACCOUNT                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   Tenant A  │    │   Tenant B  │    │   Tenant C  │     │
│  │             │    │             │    │             │     │
│  │  Users      │    │  Users      │    │  Users      │     │
│  │  Roles      │    │  Roles      │    │  Roles      │     │
│  │  Sessions   │    │  Sessions   │    │  Sessions   │     │
│  │  Policies   │    │  Policies   │    │  Policies   │     │
│  │  Settings   │    │  Settings   │    │  Settings   │     │
│  │  API Keys   │    │  API Keys   │    │  API Keys   │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  Shared Infrastructure                                      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │ Risk     │ │ Audit    │ │ Email    │ │ Webhooks     │   │
│  │ Engine   │ │ Logs     │ │ Service  │ │ Dispatcher   │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
└─────────────────────────────────────────────────────────────┘

Tenants

A tenant represents an organization — your customer, a business unit, or your own company. Every resource in the system is scoped to a tenant. Tenants are completely isolated from each other.

Users

A user belongs to exactly one tenant. Users authenticate with email + password, optionally with MFA (TOTP). Each user has a profile, verification status, and zero or more assigned roles.

Sessions

Every successful login creates a session. Sessions track the device (user-agent), network (IP address), and activity (last_active_at). They're stored in both PostgreSQL and Redis for fast lookup.

• •Limits: Configurable max sessions per user. When exceeded, the oldest session is auto-revoked.
• •Timeout: Configurable inactivity timeout. 0 = no timeout (uses refresh token lifetime).
• •Revocation: Sessions can be revoked individually or all-at-once by admins.
• •Anomaly detection: The risk engine monitors for unusual patterns (UA change on same IP, IP hopping mid-session).

Tokens

Vyntech Account issues two types of JWT tokens, both signed with Ed25519 (EdDSA):

Roles & Permissions

RBAC (Role-Based Access Control) is the primary authorization model. Each tenant has system roles (owner, admin, member, viewer) and can create custom roles.

• •Roles are scoped to a tenant. They contain a set of permissions.
• •Permissions are resource:action pairs (e.g., users:read, roles:assign).
• •User-role assignments can be scoped (tenant-level or platform-level) and can have expiration dates.

Permissions are included in the access token claims, so your backend can check authorization without additional API calls.

Cedar Authorization Policies

For fine-grained access control beyond RBAC, Vyntech Account uses Cedar — a policy language developed by AWS. Cedar policies evaluate permit/forbid decisions based on principal, action, resource, and context.

// Allow owners to manage all resources in their tenant
permit (
  principal in Role::"owner",
  action,
  resource
) when {
  resource.tenant == principal.tenant
};

// Forbid suspended users from any action
forbid (
  principal,
  action,
  resource
) when {
  principal.status == "suspended"
};

Policies are evaluated via the POST /api/v1/authz/check endpoint or embedded in your backend using the Cedar evaluation library.

Tenant Settings

Every tenant has a settings object (stored as JSONB) that controls behavior across 6 categories:

Settings are merged (not replaced) on save, cached in Redis for 5 minutes, and enforced on every auth operation. See the Tenant Settings guide for details.

Risk Engine

Every login is evaluated by the behavioral risk engine. It computes a score (0–100) based on multiple signals and compares it against the tenant's configured thresholds.

Audit Logs

Every action is recorded in an immutable audit trail: logins, failed attempts, role changes, policy updates, session revocations, settings modifications. Each entry includes the actor, IP address, timestamp, resource, and status. Retention is configurable per tenant (plan-dependent defaults: 7 days free, 90 days pro, 1 year enterprise).

Plans & Quotas

Each tenant is on a plan that determines default limits, available features, and configurable settings. Limits can be overridden per-tenant via the admin panel. All plans include the core identity engine and audit logging.

What's Next