#Tenant Scoping

5 min read

#Overview

AiDial uses tenant scoping to ensure that customer and partner users only see data they are authorised to access. A "tenant" in AiDial is a client organisation. Many operational surfaces are also project-scoped.

Browser users sign in through the AiDial portal and should not send X-API-Key. API keys are for trusted direct server-side integrations. The portal uses a Backend-for-Frontend (BFF) model: browser requests go to portal pages or app/api/** route handlers, and the portal server calls aidial_api with a server-side bearer token.

Role, tenant, tenant status, and project scope are resolved during sign-in from the DB-backed session context returned by aidial_api, then cached in the signed NextAuth session cookie. The browser session object does not expose the upstream access token.

#How Tenant Scoping Works

#Customer Roles (Single Tenant)

If you have a customer role (client_admin, client_manager, or client_staff), portal activity is scoped to the client_id resolved for your session and to the project IDs assigned to that client account.

  • You do not need to select a tenant; your account is bound to one client_id
  • Project-specific routes use your assigned project_ids; out-of-scope project IDs are rejected without revealing whether they exist
  • You cannot view, search, or access data from other organisations
  • Portal requests add only the tenant/project scope that the route has resolved
  • Project-dependent Settings sections expose browser-safe project references where implemented; the BFF maps those references back to raw project IDs server-side before calling aidial_api

#Partner Roles (Multiple Tenants)

If you have a partner role (partner_admin or partner_user), you may have access to multiple client organisations. Partner access works differently from customer access:

  • Access is assignment-based — Partner routes use assigned client and project IDs from your account context.
  • Access is per-route — Some routes can aggregate across assigned clients or projects. Others require an explicit target client_id or project_id.
  • Cross-tenant access is still restricted — You can only access clients and projects that have been explicitly assigned to your partner account. Unassigned targets receive non-enumerating denial responses.
  • Role still matters — partner_admin can perform partner management actions where implemented. partner_user is read-only on partner surfaces and is not permitted to access billing.

#Explicit Client Selection for Partners

For certain portal features, the route must explicitly resolve which client or project is being accessed. This applies to:

  • Billing — partner_admin must supply an assigned client_id for billing overview, invoices, invoice PDFs, and billing portal sessions. Missing or unassigned clients are rejected. partner_user cannot access billing.
  • Calls and analytics — Call search and dashboard routes use the resolved client/project scope. When a session has multiple project scopes, call search requires an explicit in-scope project_id.
  • Projects workspace — Partner project routes use assigned project IDs from the session context and return 404 for unassigned project IDs.
  • Project-specific settings — Opening hours, call limits, compliance copy, transfer settings, notification preferences, and related project-delivery settings resolve the selected project from the signed-in session's allowed project_ids. Multi-project sessions must select a project before reading or mutating a project-specific setting. Where the route exposes project_ref, treat it as the browser-safe selector; the raw project ID is resolved server-side.
  • Client-scoped settings — Tenant settings, IP allowlisting, entitlements, data governance, and billing-style routes resolve a tenant/client scope before work is performed.

This design ensures partner actions are scoped to a specific assigned client or project before any request is made.

#AiDial Operations Roles

AiDial operations-only roles are platform-scoped and are not assigned to customer or partner users. They are outside the normal customer and partner tenant model.

#Tenant Status

Portal access requires your organisation to have an active account status. If your organisation's status changes:

  • Active — Full portal access as permitted by your role
  • Suspended — Portal access is denied. Contact your AiDial account manager or AiDial support.
  • Provisioning, archived, or deleted — Portal access is denied. Contact AiDial support for assistance.

AiDial checks tenant status before protected portal work is performed.

#Enforcement Summary

Tenant and project scope is enforced server-side by the AiDial portal and aidial_api:

  • Portal pages and actions validate the signed-in session, tenant status, role, MFA state where required, and requested scope.
  • Middleware covers non-API page routes, applies the route-permission allowlist, and rewrites unsupported or out-of-role access to non-enumerating states.
  • Portal API route handlers live under app/api/. Middleware intentionally bypasses /api/, so each protected route handler must enforce its own auth, RBAC, CSRF where applicable, and tenant/project/client scope.
  • BFF transport lives under lib/aidial-api/, validates upstream /v1/ paths, strips forwarded X-API-Key, and injects Authorization: Bearer <access-token> server-side.
  • Direct API requests must use the authentication method and scope supplied for that integration. Browser portal flows use bearer-backed BFF routes rather than browser-supplied API keys.
  • Compliance-sensitive actions are checked against role and scope before any sensitive information is shown.
  • Navigation is a user-interface convenience only. It is not a security boundary.

#Data Isolation Guarantees

  • Customer-facing data is scoped to the authenticated client_id and, where applicable, assigned project_ids.
  • Partner-facing data is scoped to assigned clients and projects. Partner routes must not trust a browser-supplied client or project ID until the route has validated that assignment server-side.
  • Browser-safe project references may be used on Settings surfaces to avoid exposing raw project IDs unnecessarily. They are selectors only; the server still validates and resolves them against the session scope.
  • Internal admin cross-tenant operations are explicit admin surfaces, not customer or partner tenant views.
  • Out-of-scope client and project requests return non-enumerating responses such as 404 Not Found rather than revealing that a resource exists elsewhere.
  • The portal session object exposed to the browser does not include upstream access tokens.

#Required Runtime Configuration

Tenant scoping depends on the standard portal auth and BFF runtime configuration. These values are required; the current code does not define fallback defaults for them:

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

#Next Steps