Contact

Foundations

Accounts, Organizations & Locations

The three-tier tenant hierarchy determines policy scope, reporting boundaries, and operational ownership across all Cadres features.

Technical Manual
Status: Available

Tenant hierarchy

Cadres uses a three-level hierarchy. Every resource in the system -- hosts, alerts, patches, jobs -- belongs to this tree. Understanding it is essential before configuring anything else.

Account Organization A Organization B Location: DC-East Location: DC-West Location: Cloud-US Location: Cloud-EU
Account The top-level tenant boundary. Represents a single customer or managed entity. All billing, administrative ownership, and data isolation is at this level. Account-scoped roles grant access across all organizations within the account.
Organization An operational or business segmentation layer under the account. Typically maps to a department, business unit, or managed client. Each organization has its own secret key, hosts, policies, and alert rules. Org-scoped roles restrict access to a single organization.
Location A network and physical context under an organization. Used for host placement and policy scope. Locations can have subnet definitions (CIDR ranges) for automatic host assignment. Common examples: data centers, cloud regions, branch offices.
Account admins Account administrators are not assigned to a specific organization. They can access all organizations within the account.

Creating and managing organizations

Organizations segment your infrastructure into operational boundaries. Requires settings.manage permission.

Creating an organization

  1. Navigate to Settings > Organizations.
  2. Click Create Organization.
  3. Enter the organization name and optional description.
  4. An organization secret is automatically generated. This secret is used by agents during registration to associate themselves with the correct organization.
  5. Click Save.

Editing an organization

  1. Navigate to Settings > Organizations.
  2. Click the organization row to open the detail view.
  3. Edit the name, description, or other metadata.
  4. Click Save.
Organization secret The organization secret is a sensitive credential. It is used by every agent in that organization to authenticate during registration and heartbeat. Treat it like a password: do not expose it in shared documentation or version control.

Creating and managing locations

Locations represent network segments or physical sites within an organization. They enable subnet-based auto-assignment of hosts.

Creating a location

  1. Navigate to Settings > Locations (within the org context).
  2. Click Create Location.
  3. Enter the location name (e.g. "DC-East", "Azure-US-West", "Branch-NYC").
  4. Optionally enter one or more subnet CIDR ranges (e.g. 10.1.0.0/16, 192.168.50.0/24). These are used for automatic host assignment.
  5. Set the timezone for the location. This is used by maintenance window scheduling.
  6. Click Save.

Subnet-based auto-assignment

When an agent registers, the backend checks the agent's reported IP address against all location subnet definitions within the organization. If a match is found, the host is automatically assigned to that location. If no match is found, the host is assigned to the organization's default location.

CIDR subnets One or more network ranges in CIDR notation. The agent's primary IP is matched against these during registration. More specific (longer prefix) matches take priority.
Timezone IANA timezone string (e.g. America/New_York). Used for maintenance window calculations and local-time display. If not set, UTC is assumed.
Default location If a host's IP doesn't match any subnet definition, it is placed in the default location for the organization. Ensure you have a catch-all default location configured.

Organization secrets and security

Each organization has a unique secret key that serves as the shared authentication credential between agents and the backend.

  • Registration: Agents send the org secret in the X-Organization-Secret header during initial registration. The backend validates it to determine which organization the agent belongs to.
  • Heartbeat: After registration, the Go agent uses Ed25519 cryptographic signing for heartbeat authentication. The org secret is only needed for initial setup.
  • Legacy agents: The legacy C agent continues to use the org secret for all requests (no Ed25519 support).
  • Terminal encryption: The org secret is also used as the shared encryption key for terminal session credential transport (AES-256-GCM).
Rotating org secrets If you need to rotate an organization secret, all agents in that organization must be reconfigured with the new secret. Plan for a maintenance window and update agents in batches. Already-registered Go agents will continue working (they use Ed25519 after registration), but any new registrations will require the new secret.

How hierarchy affects features

The account-org-location hierarchy cascades through every feature in Cadres.

Feature Scoped To Details
Hosts Organization + Location Every host belongs to exactly one org and one location. Filters on the Hosts page use this hierarchy.
Alert rules Account, Org, Location, or Host Rules can target any level. Account-wide rules evaluate across all orgs. Host-level rules target a single machine.
Patch policies Organization Patch policies are org-scoped. Deployments target host groups within the org.
Host groups Organization Groups are org-scoped. Used for maintenance windows, ring sets, and script targeting.
Maintenance windows Location or Host Group Windows use the location's timezone for scheduling. Can be set at location or group level.
RBAC roles Account or Organization Account-scoped roles grant access everywhere. Org-scoped roles restrict to one organization.
Feature flags Account or Organization Org-specific flags override account-wide flags. No flag = feature enabled by default.
Credential vaults Organization PAM vaults are org-scoped. Vault access is granted per-user or per-group within the org context.
Audit logs Account All audit entries include the account and organization for scoped filtering.

Design guidelines

Get the hierarchy right from the start -- restructuring later means moving hosts, reassigning policies, and updating role scopes.

  • Mirror real operational boundaries, not org chart aesthetics. If two departments share infrastructure and on-call, they should probably be one organization.
  • Design for delegated administration. Create org-scoped roles early so team leads can manage their own hosts without account-wide access.
  • Use locations for physical and network context. One location per data center, cloud region, or branch office. Avoid creating locations per-rack or per-VLAN unless you need that granularity for maintenance windows.
  • Set subnets on every location. Automatic host assignment eliminates manual placement errors during agent rollout.
  • Name consistently. Use a naming convention for organizations and locations that makes them sortable and searchable (e.g. prod-us-east, dev-eu-west).