Skip to content

Architecture overview

This page is the concept-level architecture overview — enough to understand how AtmanID keeps customers apart and keeps an honest record, not enough to satisfy a security review on its own. For the review-grade version (threat model, compliance mapping, sub-processors), see Architecture & Security.

It describes what each control guarantees. It deliberately does not describe how our monitoring recognises an attack: that detail helps an attacker more than it helps a reviewer.

The stack

AtmanID is a Next.js (App Router) application hosted on Vercel, backed by PostgreSQL on Neon. Iris, the assistant, uses Anthropic’s Claude for language and Voyage AI embeddings to choose which tools fit a question. Data is encrypted in transit (TLS) and at rest (managed by Neon).

Multi-tenant by design

Every customer organisation is a tenant. Every row that holds customer data is marked with its tenant, and the database will not hand a row to a request made for a different tenant.

Why one database rather than one per customer: a database per tenant multiplies deployments, migrations and backups by the number of customers, and a model with no tenant column turns every isolation failure into an application bug that is hard to see. A single database whose rows are owned by tenants, with the database enforcing that ownership, is the established pattern for multi-tenant SaaS. We follow it carefully rather than invent a new one.

How tenants are kept apart

Isolation is enforced by PostgreSQL, so a mistake in application code fails closed instead of exposing another customer’s data.

The database enforces it

Every tenant-owned table has Row-Level Security switched on, and on all but a small, deliberate set it also binds the table’s owner. Automated checks fail any change that weakens this. A row is visible to a request only when it belongs to the tenant that request is running for.

Each query runs in its own short transaction that first records which tenant it is for. A query that arrives without a tenant sees no tenant data at all, rather than every tenant’s. The application connects as a role that cannot bypass these rules; roles that change the schema are separate and are not used to serve requests. Automated checks block new code that queries tenant data outside this path.

The result: if a developer forgets to filter a query by tenant, the database still returns only the caller’s rows.

Iris never writes the SQL

Iris answers data questions through a read-only tool, and that tool does not accept SQL. The model describes the question in a fixed structure — which curated view, which columns, which filters and groupings — and the server checks every name against the view’s real columns, then builds the parameterised query itself. Nothing the model writes is ever executed as SQL, so there is no SQL for a manipulated prompt to inject into.

Those queries run:

  • through a dedicated, read-only database login that can see only the curated views;
  • inside a read-only transaction with a time limit;
  • against views that filter on the caller’s tenant, over tables whose row-level security is forced and so binds the view too;
  • with the tenant set from the signed-in user’s session — never from anything the model or the browser supplies.

Results are checked again before they are returned, and anything that should not be there is blocked and recorded in the audit log. That check is a backstop; the controls above are what keep tenants apart.

These protections are tested on every change against a library of cross-tenant attack patterns, including attempts to change the session’s tenant from inside a query.

The audit log

Everything AtmanID does is written to an audit log: who acted (a person, an AI agent, or the system — which includes API keys and scheduled jobs), what they did, to what, and the state before and after. A request ID ties together the steps of a multi-step workflow.

Three controls make the log trustworthy:

It is append-only, enforced by the database. The application’s database role can add audit rows but cannot change or delete them. A row without its integrity hash is rejected.

It is hash-chained. Each row carries a per-tenant sequence number and a hash that covers the event and the previous row’s hash. Changing any earlier row breaks every hash after it, and a missing sequence number shows that a row was removed.

The head of the chain is signed outside the database. Every few minutes the latest point of each tenant’s chain is signed with a key the database never holds, and the signature is also copied to separate storage outside our database provider. Someone who gains full control of the database still cannot produce a valid signature, so rewriting history or removing the newest entries shows up when the chain is checked against those signatures.

Every night the most recent entries of each tenant’s chain are re-verified, and every week the whole history is — each entry, and each signature against the entry it signed. A break raises an alert, including a webhook your SIEM can consume. Compliance, audit and admin roles can check up to the latest 10,000 entries on demand from the Audit Log page, or ask Iris to check the most recent ones, and get either “intact” or the exact point where it breaks. Evidence collection becomes a check rather than a project.

The Iris layer (light touch — full detail in Iris explained)

Iris chooses which of its tools can answer a question, calls them with the signed-in user’s permissions, and writes the answer from what they return. It can only reach data and actions that user could reach in the product.

Actions that change access go through a confirmation step:

  • The confirmation card shows what the action will do using values read fresh from the database, not the model’s description of them.
  • Each confirmed action is signed for that user and that tenant, can be used once, and is written to the audit log.
  • A user can let Iris carry out some actions without asking each time, for a limited period. That only ever covers actions that reduce access or change nothing about it (revoking, rejecting, running a scan). Anything that grants, extends or re-routes access always asks.

Text that arrives as data — a justification someone typed, a name synced from another system — can try to steer the model. The confirmation rules above are what stop such text from granting access: at worst it can prompt an action that reduces access, and the user still sees what was done.

Runtime enforcement for AI agents

AI agents are governed on the same identity model as people, and their tool calls are enforced at runtime:

  • An agent’s token is scoped to specific MCP servers and tools, and can be DPoP-bound so it is useless without the agent’s own key.
  • Every agent → MCP tool call passes through the AtmanID gateway, which checks the token, the server and tool scope, intent policy and rate limits, and can hold the call until a person approves it. The agent’s credentials are never forwarded to the upstream server.
  • Each server’s enforcement starts in shadow mode — calls that would be denied are recorded but still forwarded — and an operator promotes it to enforce once satisfied. Every call through the gateway is recorded.

What the architecture does not do

Important to be honest about the boundaries:

  • Synced data is not instant. Identity providers that support SCIM 2.0 push user and group changes to AtmanID as they happen. Account and entitlement data from connected applications, identity sources and file feeds is synced on a schedule — daily by default — or on demand from the application’s page. Between syncs, AtmanID reflects the last sync; a change made and reversed inside that window will not appear.
  • No on-premise deployment. AtmanID is cloud-only, so air-gapped environments are not supported.
  • No federation across tenants. Each customer is one tenant, and tenants are isolated from each other; there is no primitive for granting a user in one tenant access in another.
  • No client-side encryption. Data is encrypted in transit and at rest, but AtmanID can read it to provide the service. We are not a zero-knowledge platform.

Where to go next

  • For the security-review-grade detail (threat model, compliance mapping, sub-processor list): Architecture & Security
  • For how Iris chooses tools and stays accurate: Iris explained
  • For practical operational guides: Guides

© AtmanID · Privacy