Multi-Org Architecture

The Multi-Org Model

Relay is built as a multi-org platform from day one. This means each organization has its own isolated workspace — apps, agents, event logs, allowlists, everything.

When you register on Relay, you automatically get an organization. When you register an app or agent, they belong to that organization. Your apps can only talk to your agents. You can't see other organizations' data, and they can't see yours — it's enforced at the database level.

Why Multi-Org?

Multi-org architecture lets Relay scale to serve many organizations without painful migrations or refactoring. It's built into the data model from day one, not bolted on later.

Roles and Permissions

Relay has three role types. The first two operate within an organization; the third is platform-wide.

Role Hierarchy

Platform Admin (Relay platform)
  └─ Can see all organizations
  └─ Can manage platform settings
  └─ Also typically an Owner for their own organization

Owner (Your organization)
  └─ Can register and manage apps
  └─ Can register and manage agents
  └─ Can configure agent allowlists
  └─ Can invite team members to their organization
  └─ Can view all event logs for their organization

Member (Your organization)
  └─ Read-only access to dashboard and event logs
  └─ Cannot register apps/agents or modify settings

Permission Matrix

Action	Platform Admin	Owner	Member
Create/register apps	All organizations	Own organization	❌
Create/register agents	All organizations	Own organization	❌
Configure allowlists	All organizations	Own organization	❌
View event logs	All organizations	Own organization	✅
Invite team members	(N/A)	Own organization	❌
Manage organization settings	All organizations	Own organization	❌
View connection status	All organizations	Own organization	✅
Rotate app/agent tokens	All organizations	Own organization	❌
Deactivate apps/agents	All organizations	Own organization	❌

Organization Isolation

All data in Relay is scoped by org_id at the database level. This isn't a suggestion — it's enforced.

How It Works

Every resource in Relay belongs to an organization:

Organization
├── Apps
│   ├── app_id: "portal", org_id: <ckgworks>
│   └── app_id: "flow", org_id: <ckgworks>
├── Agents
│   ├── agent_id: "athena", org_id: <ckgworks>
│   └── agent_id: "klyve", org_id: <ckgworks>
├── Allowlists
│   ├── athena → portal (org: <ckgworks>)
│   └── klyve → flow (org: <ckgworks>)
└── Event Logs
    └── All events tagged with org: <ckgworks>

Queries Are Always Scoped

Every database query includes WHERE org_id = ?. A few examples:

-- Get all apps for this organization
SELECT * FROM apps WHERE org_id = $1;

-- Check allowlist (organization-scoped)
SELECT * FROM agent_allowlist
WHERE org_id = $1 AND agent_id = $2 AND app_id = $3;

-- Get event logs for this organization
SELECT * FROM events WHERE org_id = $1 ORDER BY created_at DESC;

This means:

• ✅ An app with token rlk_portal_... can only see agents in its organization
• ✅ Agent discovery returns only agents in the app's organization
• ✅ Event logs are automatically filtered to the organization
• ❌ You cannot access another organization's data, even if you somehow get an app token from it

Cross-Org Isolation

Relay enforces hard boundaries between organizations:

What Each Organization Can See

Organization A	Organization B
✅ Its own apps	❌ Org B's apps
✅ Its own agents	❌ Org B's agents
✅ Its own event logs	❌ Org B's event logs
✅ Its own allowlists	❌ Org B's allowlists
✅ Its own team members	❌ Org B's team members

Sharing Agents (Future)

In v1, cross-org agent sharing is not supported. If Acme Corp wants to let StartupXYZ use their Athena agent, that's out of scope. This might be a future feature.

For now, agent isolation is complete.

Practical Example

Let's say Acme Corp has registered these resources:

Acme Corp Organization
├── Apps:
│   └── Portal (rlk_portal_acme_...)
├── Agents:
│   ├── Athena (rla_athena_acme_...)
│   └── Klyve (rla_klyve_acme_...)
└── Allowlist:
    ├── Athena ← Portal ✓
    └── Klyve ← Portal ✓

When Portal sends an event to Relay:

1. Relay extracts the token → identifies organization (Acme Corp)
2. Relay checks: does this organization have an agent named "athena"? ✓
3. Relay checks: is Portal allowlisted for Athena? ✓
4. Relay forwards to Athena's WebSocket ✓

If a different organization's app tried to use Portal's token, Relay would reject it — tokens are bound to organizations.

You and Organizations

When you create your account:

1. Relay creates one organization for your organization
2. You become owner of that organization
3. You can invite others as members or additional owners
4. All your apps, agents, and logs live in this organization

If you work for multiple organizations, you might have access to multiple organizations (appearing in an organization switcher). But you're still a member of each organization independently.

Summary

• Isolation: Every organization is data-isolated at the database level
• Permissions: Roles determine what you can do within your organization
• Security: Cross-org access is impossible by design
• Simplicity: Your apps only see your agents; your logs only contain your events

This model scales: Relay can serve hundreds of organizations, each completely isolated from the others.