Skip to content

Authentication Glossary

Terminology and definitions for the authentication system.

A

Access Token - Short-lived JWT token (6 hour TTL) - Contains user claims (user_id, team_id, role, permissions) - Stored in HttpOnly cookie - Validates statelessly without DB lookup

Active Session - Database record tracking user's current refresh session - Enforces single-session enforcement - Contains device fingerprint, IP, geo, last_seen_at

Authentication (AuthN) - Process of verifying user identity - Methods: Email/password, OTP, TOTP - Results in JWT token issuance

Authorization (AuthZ) - Process of determining user permissions - Based on role and permissions - Enforced via require_permission() dependency

B

bcrypt - Password hashing algorithm - Configurable cost factor (rounds) - Salts hashes automatically

Blacklist - Redis-based token revocation - Key format: blacklist:{jti} - Checked on every token validation

C

Concurrent Login - Multiple simultaneous login attempts - Handled via approve/deny workflow - Returns 423 Locked if pending

Correlation ID - Unique request identifier - Set by CorrelationIdMiddleware - Propagated through all logs

CSRF (Cross-Site Request Forgery) - Attack type exploiting authenticated sessions - Prevented via double-submit cookie pattern - Required on state-changing endpoints

D

Device Approval - OTP-based verification for new devices - Email sent with 6-digit code - Required for unknown device fingerprints

Device Fingerprint - SHA-256 hash of user agent + IP - Used to recognize trusted devices - Stored in TrustedDevice table

Double-Submit Cookie Pattern - CSRF prevention method - Cookie value must match header value - Checked on protected endpoints

Door A Registration - User creates new team - Becomes Owner after billing upgrade - Requires team name and slug

Door B Registration - User joins existing team - Via invite token - Assigned invited role

E

Email Verification - Required before login - 24-hour TTL on tokens - Single-use tokens

Encryption Key (Fernet) - Symmetric encryption key - Used for Virtuozzo credentials - 32-byte base64 urlsafe

F

Fernet - Symmetric encryption algorithm - Used for secrets at rest - Provides confidentiality + integrity

H

Hashed OTP - OTP stored using HMAC-SHA256 - Prevents plaintext OTP in Redis - Uses ENCRYPTION_KEY

HttpOnly Cookie - Cookie flag preventing JavaScript access - Used for access/refresh tokens - Protects against XSS theft

I

Idle Timeout - Maximum inactivity period - Default: 60 minutes - Enforced on token refresh

Invitation Token - Single-use team invitation - 7-day TTL - Converted to TeamMember on acceptance

J

JWT (JSON Web Token) - Token format for access/refresh tokens - HS256 algorithm (HMAC-SHA256) - Contains claims: sub, iat, exp, jti, etc.

JTI (JWT ID) - Unique token identifier - UUID4 hex string - Used for blacklisting/revocation

L

Login Activity - Audit log of login/refresh events - Contains IP, user agent, geo, device - Used for suspicious login detection

M

Middleware Chain - Ordered request processing pipeline - Order: CorrelationId → CORS → OTEL → AuthContext → RequestLogging - Registered in reverse in app_factory.py

Multi-Tenancy - Users belong to teams - Access scoped to team membership - Enforced at middleware level

O

Ownership Transfer - Process to transfer Owner role - Email-based approval - Old Owner becomes Manager

OTP (One-Time Password) - 6-digit code for device approval - 5-minute TTL - Hashed in Redis

P

Permission - String-based authorization token - Format: category.action (e.g., site.create) - Assigned to roles

Pre-Auth Token - Short-lived intermediate token - 5-minute TTL - Used in two-step login

R

RBAC (Role-Based Access Control) - Authorization model - Users → Teams → Roles → Permissions - Wildcard * grants all permissions

Refresh Token - Longer-lived JWT (7d/1d) - Used to obtain new access tokens - Session state in Redis

Role - Team-scoped collection of permissions - Default: Owner, Manager, Developer - Can be custom (except Owner)

Revocation - Server-side token invalidation - Via Redis blacklist or timestamp - Affects all user tokens

S

Salt - Random data added to password hash - Built into bcrypt - Unique per password

Session Exchange - Step 2 of two-step login - Trades pre-auth token for JWT cookies - Validates team membership

Session Info - Metadata about user session - Device, IP, geo, user agent - Tracked for security

Suspicious Login - Login from unusual location/device - Detected via LoginActivity comparison - Requires approve/deny via email

T

Team - Tenant boundary in multi-tenant system - Owned by Owner user - Contains users via TeamMember

TeamMember - Association between User and Team - Includes role assignment - Unique per (user_id, team_id)

TOTP (Time-based One-Time Password) - 2FA method using authenticator apps - pyotp library - Not yet enabled in production

Trusted Device - Persistent device approval record - Skips OTP on future logins - Can be revoked

U

User - Global identity in system - Belongs to one or more teams - Has email, hashed password

V

Virtuozzo - Infrastructure API - Session key required for operations - Owner-only refresh

W

Wildcard Permission - * grants all permissions - Assigned to Owner role only - Bypasses individual permission checks