Organization Management

Scope

How to create and manage organizations and their locations, give people from another company access through Portal, and set recording and data-retention rules for each organization.

Covers: creating organizations, managing organizations, location management, access for people from another company

Creating Organizations

Each organization gets a unique secret for agent registration (auto-generated). When an organization is created, the backend also seeds a default Location so the org is immediately usable and runs the onboarding seeders for default alert/compliance data.

Managing Organizations

Listing Organizations (Server-Side Pagination)

The organization list is fully server-side paginated. The API supports:

Parameter	Type	Default	Description
skip	int	0	Offset for pagination
limit	int	100	Page size (max 1000)
search	string	null	Search by name or description
region	string	null	Filter by exact region
active_only	bool	true	Legacy filter: show only active orgs
is_active	bool	null	Explicit active filter (overrides active_only when set)
include_stats	bool	true	Include endpoint online/offline/stale stats

The response includes X-Total-Count header with the total matching count for pagination controls.

Regions endpoint (for populating filter dropdowns): Returns a sorted list of distinct non-null region values across accessible organizations.

Updating Organizations

Update:

Automation levels (consumed by patch engine, workflow engine, drift correction, and alert auto-remediation):

• manual — all approvals required, no automatic actions
• semi_auto — auto-approve security/critical patches, runbooks need approval
• full_auto — all auto-approve, auto-deploy

Kill switch. Pausing and resuming automation is not an organization edit. record still shows whether automation is paused, since when, by whom and why; automation_paused_reason with 422 automation_pause_moved.

Deleting Organizations

Hard delete (requires organizations.hard_delete permission): Without the hard_delete query parameter, the organization is soft-deleted (deactivated). Hard delete permanently removes the organization and all associated data. Organizations with endpoints cannot be hard-deleted – endpoints must be removed first.

Major Incident Auto-Workflow

Organizations can bind an auto-launch workflow for major incidents. This setting is configurable both via API and through the organization edit modal in the UI (under “Major Incident Auto-Workflow”).

API:

UI: Open the Edit Organization modal and select from the “Major Incident Auto-Workflow” dropdown. Only active workflow definitions for the organization are shown. Select “None (disabled)” to clear the binding.

When configured, P1 incidents with 3+ affected endpoints auto-launch the referenced workflow definition. Requires organizations.edit permission.

Location Management

Locations are physical or logical groupings within an organization.

Create location with subnet:

Setting subnet_cidr enables automatic agent location assignment based on the agent’s IP address.

Access for People From Another Company

Relay has no support-access controls (removed 2026-09-21). There is nothing to enable, review, expire or disable inside Relay, and there is no “Leave customer account” action.

To let someone from another company work in your Relay, use Portal:

1. In Portal, invite the person to your tenant as a guest.

2. In Portal, give them a Relay role or add them to a group that has one. Portal decides who holds which role.

3. The person selects your tenant in Portal and launches Relay. Relay opens at the relevant workflow, drops any Relay session they had for another company, and signs them in to your account.

To remove their access, remove the role or the guest membership in Portal. Their activity is recorded in your Relay audit log as a Portal user.

Organization Secret Management

Each organization has a secret used for agent registration. Both viewing and regenerating secrets require organizations.edit permission. The secret view button in the organization table is disabled for users without this permission.

View secret:

Regenerate secret (invalidates existing agent connections):

Warning: Regenerating the secret will require reconfiguring all agents registered with this organization.

Recording Governance

Recording Policy

Control what session data is captured per organization:

Recording Retention

Override the account-level retention period per organization:

Set to null to inherit from account default (which defaults to 90 days). The effective period is floored at 7 days.

The account default itself is set through settings.view (read) and settings.manage (update). It works only on your

Enforcement runs in the terminal_recording_retention and desktop_recording_retention background loops (maintenance worker, every 6 hours, backend/core/loops/recordings.py). Each cycle walks a bounded batch of organizations and resumes from where the last cycle stopped, so retention progresses at a predictable rate on a large tenant base instead of doing every organization in one cycle. Each organization commits on its own, and the loops delete the recording file from disk before the row.

Fixed 2026-08-20: both loops previously deleted nothing at all. The query excluding held recordings was written as not TerminalRecording.legal_hold, WHERE false — so every sweep matched zero rows, silently, since the legal-hold feature shipped. Storage-quota enforcement for terminal recordings carried the same defect. If your deployment predates this fix, expect the first cycle after upgrade to reclaim a backlog.

Legal Hold

Activate legal hold to prevent all recording deletion for an organization:

When active, neither user action nor the retention loops can delete recordings. The hold is honoured at two levels: an organization-wide hold skips that organization entirely for the cycle, and a per-recording legal_hold flag protects an individual recording inside an organization that is otherwise being swept.

GDPR Data Management

Data Deletion (Art. 17)

Tenants cannot erase their own account in Relay. Erasure is a Cadres operator action: ask Cadres support. A Cadres operator runs it from the Nexus console, which calls:

• It needs the Nexus scope accounts.delete_data and an attested operator (X-Nexus-Operator-Email). No Relay role or permission reaches it.

• confirm_account_name must equal the account’s exact name. A mismatch answers 400 erasure_confirmation_mismatch and changes nothing.

• It is irreversible. The logic is erase_account_data in backend/core/account_data.py.

What erasure does:

1. It scrubs PII from the account’s audit-log rows (IP addresses masked, emails and PII-shaped keys in before/after state and metadata redacted). The audit trail’s structure and hash chain stay; only the personal data inside it is removed.

2. It scrubs the Portal directory copy Relay holds. Every portal_users row whose Portal tenant is linked to the account gets the email deleted-<id>@anonymized.local, the display name Deleted User, and is_active cleared. The row itself survives, so actor foreign keys on past actions still resolve. Linked IdP users are scrubbed the same way.

3. It deactivates the account and stamps data_deleted_at.

4. It writes the audit record nexus.account.gdpr_erase, after the scrub, so the record keeps the attested operator.

5. After commit, it fans the suspension out to every runtime backend with blocked_by="gdpr_deletion".

A repeat call on an erased account is idempotent: it returns already_erased: true, reports the counts as they stand, and writes nothing.

A later directory sync restores the scrubbed names. core/portal_directory_sync.py mirrors Portal’s answer over portal_users and does not check accounts.data_deleted_at, so a reconcile after the erasure rewrites the email and display name from Portal. Delete the person in Portal first — Portal is the controller — to make the erasure stick.

Data Export (Art. 20)

Settings > Account and select Export account data. The button appears only if you hold account_data.export. The API call is:

account.sar_export.

Covers last 90 days, capped at 10,000 records per section. Excludes passwords, secrets, and encrypted credentials.

The users section is the Portal directory Relay holds for the account — the portal_users rows reached through the account’s tenant links. Each entry what a subject matches against Portal’s own export, and id, the local portal_users primary key that every actor reference elsewhere in the export points at.

Cross-References

Topic	Document