#Authentication & Access Guide

Welcome to the AiDial portal authentication and access guide. This guide covers signing in, understanding your permissions, tenant-scoped access, session security, MFA, and API authentication for trusted partner integrations.

#Who Should Read This Guide

• Customers (client_admin, client_manager, client_staff) — Learn how to sign in, manage your account security, and understand what you can access.
• Partners (partner_admin, partner_user) — Understand how multi-tenant access works and what your partner role allows you to do.
• Developers and integration partners — Learn the difference between trusted server-side API access and first-party portal sessions, and understand error responses.

#Current Security Boundaries

• Browser users sign in through the AiDial portal with next-auth and Zitadel OIDC. Browser code calls portal pages and BFF route handlers under app/api/**; it must not call aidial_api directly or send X-API-Key.
• The portal is a Next.js App Router BFF: browser -> portal server -> aidial_api. Shared server-side transport in lib/aidial-api/** forwards the session bearer token and strips inbound X-API-Key before outbound API calls.
• API keys remain a direct aidial_api server-to-server authentication path for trusted integrations, not a first-party portal browser authentication method.
• Middleware covers non-API portal routes. API route handlers under app/api/ must enforce their own auth, RBAC, CSRF, tenant/project scoping, and response hardening through shared helpers in lib/auth/, lib/aidial-api/, and, for compliance surfaces, lib/compliance/.
• Tenant and project scope is enforced server-side with non-enumerating responses for out-of-scope resources.
• Sidebar or navigation visibility is not a security boundary.

#Required Runtime Configuration

The portal fails closed when required runtime configuration is absent. These values are required; there are no documented fallback defaults for production or preview operation:

• NEXTAUTH_SECRET
• NEXTAUTH_URL
• AIDIAL_API_BASE_URL
• AIDIAL_API_TIMEOUT_MS
• ZITADEL_ISSUER
• ZITADEL_CLIENT_ID
• ZITADEL_CLIENT_SECRET

#Guide Contents

#Getting Started

1. Signing In — How to sign in to the portal, what to expect, and how to troubleshoot common access issues.

#Understanding Your Access

1. Roles & Permissions — What customer and partner roles can see and do in the portal, including comparison tables and route-access expectations.
2. Multi-Factor Authentication — Which roles require MFA, provider-managed setup, recovery-code reminders, and what to do if you are locked out.
3. Tenant Scoping — How data isolation works, the difference between single-tenant (customer) and multi-tenant (partner) access, and how client selection works for partners.

#For Developers

1. API Authentication — How direct server-side integrations use API keys, how first-party portal BFF calls use bearer tokens, and why browser code must not send X-API-Key.
2. Error Responses — Common authentication and authorisation error codes and what they mean.
3. API Authentication — Public BFF and direct API authentication guidance, including bearer forwarding, API-key boundaries, and server-side scope enforcement.

#Security

1. Session Security — Session expiry, signing out, customer session management, administrator session revocation, and security best practices.

#Quick Reference