Organizations, Tenants, and Licenses
AxonFlow uses three identity concepts that are easy to conflate but do different jobs. Getting them straight is the key to understanding what isolation you get, and what a single license can and cannot do.
| Concept | What it is | What it controls |
|---|---|---|
| License | A deployment entitlement token | Whether an AxonFlow installation may run, and at what tier (feature set, node limit, expiry). Checked once, at startup. |
Organization (org_id) | The isolation boundary | The unit that data is partitioned by. Row-level security scopes every audit, policy, usage, and connector record to one organization. |
Tenant (tenant_id) | A runtime credential / label | Per-caller identity for attribution: audit trails, traces, and rate-limit buckets. It is not a data-isolation boundary. |
The single most important relationship: the license fixes the organization, and the tenant is just the credential's username. Two callers presenting different usernames but the same license are two tenants in the same organization.
The license — a deployment entitlement
A license answers one question: may this AxonFlow installation boot, and with which capabilities? It encodes a tier (which gates features and the node limit) and an expiry, and it is validated cryptographically when the agent starts. It identifies the deployment, not an individual end-user or workload.
A license is not a per-tenant token. Nothing in a deployment license names a tenant. You do not need a license per team, per workload, or per end-customer to attribute activity to them — that is what the tenant credential is for.
For how license tiers, hosting modes, and scopes fit together, see the License Matrix. For issuing and configuring self-hosted licenses, see Self-Hosted Licensing.
The organization — the isolation boundary
The organization (org_id) is what AxonFlow isolates on. Postgres row-level security ensures a request scoped to one organization can only read and write that organization's rows — audit logs, policies, usage, connectors, and the rest. If two workloads must not see each other's data, they must be in different organizations.
In most deployments the organization is set once, at deployment time, and is the same for every request that installation handles.
The tenant — a runtime credential label
When a caller authenticates, AxonFlow takes the username from its credentials as the tenant_id. This label rides along on every decision, audit record, and trace span, and it drives per-tenant rate-limit buckets. It is ideal for attributing activity to a team, service, or environment.
Because the tenant is derived from the credential username and the organization comes from the deployment, many tenants can share one organization. That gives you per-tenant attribution for free — but, by design, tenants in the same organization are not isolated from one another (row-level security operates at the organization level). See Multi-tenancy below.
Programmatic callers authenticate with HTTP Basic auth (clientId/clientSecret), where the clientId is the tenant username and the clientSecret is the deployment's license key — the same key for every tenant on that deployment. That shared key is exactly why those tenants resolve to the same organization, and therefore are not isolated from one another. For the full authentication story — including enterprise SSO, SAML, and SCIM for human portal access — see Identity & Access Management and SDK Authentication.
What each deployment mode supports
A deployment's DEPLOYMENT_MODE determines how the organization and tenant resolve, and therefore where the isolation boundary sits.
| Deployment mode | Organization (org_id) | Tenant (tenant_id) | Isolation boundary |
|---|---|---|---|
| Community (self-hosted, free) | A single local organization | Not enforced — requests run with a default identity | One local org; not designed for multi-tenant use |
Community SaaS (our hosted free tier, try.getaxonflow.com) | Per registered customer — each signup gets its own organization | Equals the customer's organization | Per customer — each customer is its own organization, so customers are isolated from one another |
| SaaS (we operate the agent for you) | A single operated organization (the hosted per-customer pattern is Community SaaS, not plain SaaS) | Per-credential label | The single operated organization |
| In-VPC Enterprise (you operate the agent in your own VPC) | The licensed organization, fixed at deployment | The Basic-auth username (a label) | The single licensed organization; multiple usernames are tenants within it, not isolated from each other |
A few consequences worth calling out:
- Self-service registration is Community-SaaS only. The
/api/v1/registerendpoint that mints per-customer credentials exists only in Community SaaS. In self-hosted modes you configure the organization and credentials yourself. - Community SaaS customers share the hosted platform, but each customer is its own organization, so their data is isolated from other customers. They do not, however, get to run isolated sub-tenants beneath their own organization (see below).
- Community is single-organization. It is built for local development, self-hosted testing, and single-team use — not for partitioning multiple parties.
What Community cannot do
Community is the free, self-hosted edition. Relative to Enterprise, it does not include:
- Enterprise tier features — the broader governance, compliance, and identity capabilities gated behind the Enterprise tier (see Community vs Enterprise).
- Enterprise human-identity features — SSO, SAML, and SCIM provisioning for portal access are Enterprise capabilities (Identity & Access Management).
- Hosted self-service registration — that is a property of Community SaaS, not self-hosted Community.
Community is single-organization and not intended for isolating multiple distrusting parties; for that you choose an organization-per-boundary model under a paid edition.
Multi-tenancy: what one license can and cannot do
This is where the three concepts pay off — and where it is easy to over-reach. Two different questions have two different answers:
"Can I attribute activity to many tenants under one license?" — Yes, today. Use a distinct credential username per tenant against the same deployment. Each gets its own identity in audit trails, traces, and rate-limit buckets, with no per-tenant registration and no per-tenant license. There is no cap on the number of tenants.
"Are those tenants isolated from each other?" — No. They share one organization, and isolation is at the organization level. Tenants under one license can read each other's audit, policy, usage, and connector data. The tenant label is for attribution, not isolation.
If two parties must not see each other's data, do not rely on separate tenant usernames under one organization. Put each party in its own organization.
So choose the model that matches your trust assumptions:
- Trusted internal units (teams, cost centers, environments) under one organization/license → many tenant usernames. You get attribution and separate rate limits; cross-unit visibility is accepted.
- Mutually-isolated parties (your own end-customers, regulated business units) → one organization and one license per isolation boundary. This is the supported, provably-isolated model today (it is how AxonFlow isolates customers on its own hosted platform).
- Pooled per-tenant isolation under a single organization/license — many mutually-isolated tenants sharing one organization — is on the roadmap and not available today. Because it is a data-isolation boundary, it is being designed deliberately rather than approximated. Until it ships, use organization-per-boundary for parties that must be isolated.
Related
- Identity & Access Management — authentication overview (SDK auth, SSO, SAML, SCIM)
- SDK Authentication — Basic auth with
clientId/clientSecret - License Matrix — license hosting modes × scopes × tiers
- Self-Hosted Licensing — issuing and configuring self-hosted licenses
- Community vs Enterprise — edition feature comparison
