Accounts, Tenants & Workspaces

Infracast organizes everything around three layers. Understanding how they fit together is essential before inviting users, adding credentials, or running discovery against multiple environments.

Account  (billing relationship)
  └── Tenant  (customer organization — users, RBAC, policies)
        └── Workspace  (data scope — credentials, scans, findings, reports)
              └── Resources, Findings, Credentials, Reports, ...

Most customers will only ever see one Account, one Tenant, and one Workspace. The structure exists for the cases where that's not enough.

Account

An Account is the top-level billing and subscription boundary. One Account ≈ one paying customer.

An Account owns:

The subscription (plan tier, billing source — Stripe or AWS Marketplace)
The license limits (max nodes, max workspaces, enabled plugins)
The owner (the user who signed up)
One or more Tenants
Account memberships (users with cross-tenant access at the account level)

You cannot have data directly under an Account — data always lives inside a Workspace, which lives inside a Tenant.

Tenant

A Tenant is a customer organization inside an Account. For most customers, the Account and the Tenant are 1:1 — one signing entity, one tenant. For MSPs and holding companies, an Account can contain multiple Tenants (one per managed customer or subsidiary).

A Tenant owns:

The users and roles (tenant-admin, operator, viewer)
Tenant-level policies (require MFA, branding, contact info)
Compliance settings (enabled frameworks, alert preferences)
One or more Workspaces
Tenant memberships (which users belong to this tenant)

A Tenant is an isolation boundary for users and access policies. It is not, by itself, where data lives — for that, you need a Workspace.

Workspace

A Workspace is a scoped data environment inside a Tenant. This is where the actual operational data lives.

A Workspace owns:

All discovered nodes and edges (the asset graph)
All credentials used by discovery and scanning
All findings, evidence, and POA&M items
All scan jobs and their history
All business services, applications, and reports
All compliance assessments and questionnaire responses

Every Tenant has at least one Workspace. New tenants get a default workspace auto-created (slug default, named after the tenant) when they're created. You can add more workspaces later from Settings → Workspaces or via the API.

Every record in the system carries both a tenant_id and a workspace_id. The storage layer enforces this on every query — there is no API path that returns data across workspace boundaries.

When to use multiple Workspaces

A single Workspace per Tenant is fine for most customers. Create additional Workspaces when you need hard data isolation between environments, such as:

Prod / Staging / Lab — keep test discoveries from polluting production findings
Different AWS accounts — separate prod vs dev vs govcloud
Subsidiaries / Business Units — separate Acme Corp from Acme Federal under one billing relationship
MSP customers — one Workspace per managed customer; MSP staff with Tenant-Admin role can switch between them
Different compliance scopes — keep CMMC-scoped systems isolated from non-scoped corporate IT

If you don't have a clear isolation requirement, stay with one Workspace and use Business Services or tags to organize within it. Multi-workspace adds operational overhead (separate credentials, separate scans, separate dashboards).

Self-serve signup automatically creates the full structure for you:

An Account named after your organization
A Tenant (customer org), also named after your organization
A default Workspace inside that Tenant (slug default, named after the tenant)
Your user, set as Account Owner and Tenant Admin

You can start running discoveries immediately. Additional Workspaces are optional and can be created later from Settings → Workspaces or via the POST /api/v1/workspaces API.

AWS Marketplace signups follow the same flow — the SaaS registration handler creates the Account, the default Tenant, the default Workspace, and the user atomically.

How credentials are scoped

Credentials are scoped to a Workspace, not to a Tenant or Account.

This is intentional and reflects how real environments work:

Your Prod workspace gets the prod AWS credentials, prod vCenter creds, prod Active Directory bind account
Your Staging workspace gets staging credentials
A discovery job in one workspace cannot accidentally use credentials from another workspace
Rotating a credential in one workspace doesn't affect any other workspace
An audit log entry for credential use always includes the workspace context

If you operate the same target system from multiple workspaces (rare), you create the credential separately in each workspace. The encrypted secret is stored once per workspace; there is no shared credential vault across workspaces.

The same scoping applies to:

Connectors / discovery plugin configs — per workspace
Scan schedules — per workspace
Notification destinations (Slack, Teams, PagerDuty webhooks) — per workspace
GRC integrations (eMASS, ServiceNow, Archer, CSAM) — per workspace
Discovered assets, findings, evidence, POA&M, reports — per workspace
API tokens — per workspace, scoped to the issuing user's role

Users and memberships

Users have two kinds of relationships to your data:

Account Membership

Account Membership says "this user belongs to this Account." Account-level roles include:

Owner — full control, including billing and Account deletion
Admin — manage tenants, users, billing, plugin enablement
Member — basic Account-level access (rare; most users get tenant memberships instead)

An Account Owner can switch into any Tenant under the Account.

Tenant Membership

Tenant Membership says "this user has a role inside this specific Tenant." Tenant roles:

Tenant Admin — manage everything inside this tenant (users, all workspaces, settings)
Operator — run scans, view findings, edit business services in any workspace within the tenant
Viewer — read-only access across the tenant
(System Admin is a platform-wide role used by Infracast operations, not a tenant role)

A user can have memberships in multiple Tenants with different roles in each — for example, Tenant Admin in acme-corp and Viewer in acme-fed (under the same MSP Account).

When a user belongs to more than one Tenant, the Tenant Picker appears at login. When a user has access to more than one Workspace within their active tenant, the Workspace Switcher in the header lets them flip between them without re-authenticating.

Data flow at a glance

        Account "Acme MSP"
        ├── Tenant "acme-corp"   (alice = admin, bob = viewer)
        │     ├── Workspace "default"   (= Acme Corp prod data)
        │     │     ├── credentials/aws-prod-readonly
        │     │     ├── credentials/vcenter-prod-svc
        │     │     ├── nodes/* (workspace_id = acme-corp/default)
        │     │     └── findings/* (workspace_id = acme-corp/default)
        │     └── Workspace "staging"
        │           ├── credentials/aws-stage-readonly
        │           └── nodes/* (workspace_id = acme-corp/staging)
        │
        └── Tenant "acme-fed"   (alice = admin, carol = admin)
              └── Workspace "default"
                    ├── credentials/aws-govcloud-readonly
                    └── nodes/* (workspace_id = acme-fed/default)

Alice has Account-level access and can switch between both tenants and all three workspaces.
Bob can only see acme-corp and only its default workspace (unless given workspace-level access to staging too).
Carol can only see acme-fed.
The AWS GovCloud credential cannot leak into acme-corp because it's stored under a different workspace_id (and a different tenant_id).

API quick reference

Action	Endpoint
List your tenants	`GET /api/v1/account/tenants`
Create a tenant	`POST /api/v1/account/tenants` (`{ "name": "..." }`) — auto-creates a default workspace
Switch active tenant	`POST /api/v1/auth/select-tenant` (`{ "tenant_id": "..." }`)
List workspaces in current tenant	`GET /api/v1/workspaces`
Create a workspace	`POST /api/v1/workspaces` (`{ "name": "..." }`)
Rename a workspace	`PATCH /api/v1/workspaces/{id}` (`{ "name": "..." }`)
Delete a workspace	`DELETE /api/v1/workspaces/{id}` (cannot delete the default or only workspace)
Switch active workspace	`POST /api/v1/auth/switch-workspace` (`{ "workspace_id": "..." }`)
List workspace credentials	`GET /api/v1/credentials` (auto-scoped to active workspace)
Invite a user to your account	`POST /api/v1/account/invites`
Add a user to a specific tenant	`POST /api/v1/tenant/users`

All non-account/non-workspace endpoints are automatically scoped to your currently selected workspace via the JWT workspace_id claim. You don't pass a workspace ID — switching workspaces issues a new token bound to that workspace.

The JWT carries:

{
  "user_id":      "...",
  "account_id":   "...",
  "tenant_id":    "...",
  "workspace_id": "...",
  "role":         "tenant-admin"
}

Common questions

Do I have to use multiple workspaces? No. One workspace (the default) is enough for most organizations.

Do I have to use multiple tenants? No. One tenant per account is the typical case. Multiple tenants are for MSPs, holding companies, or customers who want to bill one entity but isolate users between subsidiaries.

Can I move data between workspaces? Not directly. Workspaces are isolation boundaries by design. If you need to relocate assets, re-run discovery in the target workspace.

Can two workspaces share credentials? No. Create the credential in each workspace where it's needed.

Does each workspace have its own URL? No. All workspaces are accessed via app.infracast.io. Your active workspace is determined by your session.

How do I delete a workspace? DELETE /api/v1/workspaces/{id} — Tenant Admin only. The default workspace cannot be deleted; if it's the only workspace, it cannot be deleted either. All data scoped to a deleted workspace is removed.

What happens to data if I delete a tenant? All workspaces under the tenant are deleted, and all data scoped to those workspaces is removed. Cannot be undone.

Account​

Tenant​

Workspace​

When to use multiple Workspaces​

What you get when you sign up​

How credentials are scoped​

Users and memberships​

Account Membership​

Tenant Membership​

Data flow at a glance​

API quick reference​

Common questions​