Organizations and team members

[jimaek]

We are starting to get requests about opening an Org account with multiple people having access to it.
This is going to be especially important once we have analytics and charts in the dashboard
Any ideas how we could build this and how difficult it would be?

[MartinKolarik]

I already looked into this in the context of #138, and we can certainly add this on top of the Directus user/permission handling. Won't be easy as it affects most of the operations, but I agree we're getting to the point where it's needed.

[alexey-yarmosh]

Default Directus multi-tenancy approach with a new orgs table and an account entity is the most valid for us.

Directus updates:

1. New gp_orgs table. Columns: id, github_id, name, adoption_token.
2. New gp_org_members junction table. Columns: id, org, user, role: viewer | member | admin, notification_preferences.
3. New gp_accounts table. Columns: id, user (o2o to directus_users), org (o2o to gp_orgs). Exactly one of user/org is set. A row is auto-created for every user and org (backfill migration + DB
   trigger on insert) and removed via FK cascade, so an account always exists.
4. New column account_id in data tables:

• gp_probes (userId => account_id)
• gp_tokens (+account_id, user_created stays to track creator)
• gp_apps_approvals (+account_id; user => user_created, same as in gp_tokens)
• gp_credits (user_id => account_id)
• gp_credits_deductions (user_id => account_id)

5. User policy permissions per table. Reusable filters:

• MY_ACCOUNTS (personal or any of my orgs): { "_or": [ { "account_id": { "_in": "$CURRENT_USER.account.id" } }, { "account_id": { "_in": "$CURRENT_USER.memberships.org.account.id" } } ] } — _in with a $CURRENT_USER path is a two-step search (1: get my account ids, 2: indexed filter by them), so it's efficient. account is a reverse o2m alias on directus_users/gp_orgs.
• MINE_OR_ADMIN (personal, or admin of the owning org): { "_or": [ { "account_id": { "user": { "_eq": "$CURRENT_USER" } } }, { "account_id": { "org": { "members": { "user": { "_eq": "$CURRENT_USER" }, "role": { "_eq": "admin" } } } } } ] }

New rules only (existing clauses like tokens' app_id _null / user_created _eq $CURRENT_USER stay as they are):

Table	Action	New rule
gp_probes	read	filter => MY_ACCOUNTS
gp_probes	update	filter => MINE_OR_ADMIN
gp_tokens	create	Since validation is payload-only (no relational traversal), the payload check lives in the filter hook: account_id must be my personal account or an org where my role is admin/member.
gp_apps_approvals	—	no user policy (as today); the applications endpoint gains account scoping
gp_credits	read	filter => MY_ACCOUNTS
gp_credits_deductions	read	filter => MY_ACCOUNTS
gp_credits_additions	read	+ _or branch: { "github_id": { "_in": "$CURRENT_USER.memberships.org.github_id" } }
gp_orgs (new)	read	{ "members": { "user": { "_eq": "$CURRENT_USER" } } }. adoption_token is visible only to org admins: stripped for other roles by a read hook (permission fields can't differ per branch).
gp_orgs (new)	update	{ "members": { "user": { "_eq": "$CURRENT_USER" }, "role": { "_eq": "admin" } } }; fields: adoption_token (regenerate)
gp_org_members (new)	read	{ "_or": [ { "user": { "_eq": "$CURRENT_USER" } }, { "org": { "members": { "user": { "_eq": "$CURRENT_USER" }, "role": { "_eq": "admin" } } } } ] } — member sees own row, admin sees all
gp_org_members (new)	update	{ "_or": [ { "user": { "_eq": "$CURRENT_USER" } }, { "org": { "members": { "user": { "_eq": "$CURRENT_USER" }, "role": { "_eq": "admin" } } } } ] }; fields: role, notification_preferences. Per-field rules in a filter hook (like the gp_tokens create): role - only by an admin of that org, notification_preferences - only on own row.

Business logic updates:

Users

• User joins/leaves the org only through GitHub update -> sync.
• Header sub-menu has an "Act as organization" button+modal, which stores activeOrg in FE store + cookie.
• Any admin can set the viewer/member/admin role for any other viewer/member/admin. Automatic GitHub sync only promotes a viewer/member to admin (if they are admins on GitHub), but never demotes back (because they might have been manually promoted previously).
• New 'viewer' role is read-only: a viewer sees org data but can't create tokens/approvals or spend org credits. Adopting probes into the org is admin-only.

Probes

• A probe has a single owner: account_id (personal or org account).
• For adoption tokens, the owner is determined by the token (user's or org's adoption token). For adoption by IP or local server - by activeOrg.
• Only an admin can adopt a probe into the org: members don't see the org adoption token and can't adopt by IP or local server either.
• Admin, member, and viewer can view all org probes.
• Only admin can edit org probe metadata (city, name).
• Only admin can unassign the probe from the org. But nothing prevents it from being assigned back, e.g. if adopted by an org token, it will be assigned again automatically.
• If another user (not from org A) adopts a probe which belongs to org A, the probe is reassigned to the new owner.
• The default_prefix setting is removed; the prefix is determined based on account_id.
• The prefix select for probe tags is removed; the prefix is determined based on account_id.

Tokens

• Admin or member can create an org token to consume org credits; viewer can't.
• Credits are consumed from the token's account_id (personal or org account).
• account_id defines who pays for the token; user_created defines the creator: each user sees/manages only their own tokens.
• Tokens are deleted when their user is deleted or leaves the org (org tokens die with the membership).

Apps approvals

• Admin or member can create an app approval + token to consume org credits; viewer can't.
• An approval is bound to a specific account: consent, the "already approved" check, listing, and revoke are all per account (the same app is approved separately for the personal account and for each org).
• If the user who created an app approval leaves the org - remove the approval and its tokens (same lifecycle as plain tokens).

Credits

• Probe credits are assigned based on the probe's account_id.
• The org -> user credits redirect is no longer needed; credits are assigned directly to the org.
• The user -> org credits redirect might be needed; it can be a new setting on the user page. Out of scope.

Notifications

• Notification settings are per org and per user: each member has their own notification config for each of their orgs, independent of their personal config.
• Most org notifications are disabled by default, as there may be too many of them.

Dash UI updates

• New header menu item - "Act as organization", which opens a select org modal. The selected org is stored in a cookie and the FE store and shown in the header instead of the username.
• User doesn't have a "show all" option. So we don't have combined views.
• If an org is selected:
  • "Probes page" shows org probes in read-only/read-write state (based on role).
  • "Probe detail page" shows probe details in read-only/read-write state (based on role).
  • "Credits page" shows org credits stats (same for any role).
  • "Tokens page" shows the user's own tokens and approvals inside the org; nobody sees other members' tokens or approvals.
  • "Generate new token" creates a token inside the org (disabled for viewers).
  • "Adopt a probe" into the org is admin-only.
  • New "Organization" setting in "Settings". Only an admin can see, copy, and regenerate the org adoption token.
  • If the user is admin - a new "Organization" menu button and page, where the admin sees org info and all members, and can set member roles.

[MartinKolarik]

Two quick notes before I read in more detail:

resources should be org scoped, e.g. adopting probes should have a separate token per org, definitely not user token with manual reassign. Similarly a user leaving an org should keep the probes within the org.

Selected account can't be in Maria as that would conflict across sessions (both within the same browser and across devices), probably client state + cookie for the front end web.

[alexey-yarmosh]

adopting probes should have a separate token per org, definitely not user token with manual reassign. Similarly a user leaving an org should keep the probes within the org.

Ok, in that case no user can ever edit the orgId field as it may conflict with the adoption token pointing to the original org. And probes adopted by code or local server get orgId value based on active active_org at the moment of adoption.

Selected account can't be in Maria as that would conflict across sessions (both within the same browser and across devices), probably client state + cookie for the front end web.

Ok.

I'll update the design and let you know.

[alexey-yarmosh]

Updated.

[MartinKolarik]

First, a number of thoughts:

1. Token/app should both behave as "personal" and stop working on user removal.
2. There are also notifications. I think the most flexible and relatively easy solution is to make notification settings per org and per user; e.g., I could set one notification config for myself, another for jsDelivr events (which applies only to me), and you could set a different config for jsDelivr events that would apply only to yourself.
3. We should rework the current user fields as they are a mess, and use "userId" everywhere to represent ownership, while keeping the native directus field strictly for accountability.

All of the above can still be achieved with the userId/orgId model, though how the fields work would be table-dependent; e.g., for tokens/apps, we'd have to set both to support per-user removal.

There's also a second option: introducing an account or owner entity that's either an org or a user, and then having accountId/ownerId with an optional userId. Here's a comparison of how the checks would look in both models:

1. Account-owned resources

Collection	Direct model: personal query	Direct model: organization query	Account model
gp_probes	userId = $USER AND orgId IS NULL	orgId = $ORG	accountId = $ACCOUNT
gp_credits	userId = $USER AND orgId IS NULL	orgId = $ORG	accountId = $ACCOUNT
gp_credits_additions	userId = $USER AND orgId IS NULL	orgId = $ORG	accountId = $ACCOUNT
gp_credits_deductions	userId = $USER AND orgId IS NULL	orgId = $ORG	accountId = $ACCOUNT

2. User-owned resources

Collection	Direct model: personal query	Direct model: organization query	Account model
gp_tokens, member view	userId = $USER AND orgId IS NULL	userId = $USER AND orgId = $ORG	userId = $USER AND accountId = $ACCOUNT
gp_tokens, admin view	Same as member view	orgId = $ORG	accountId = $ACCOUNT
gp_apps_approvals, member view	userId = $USER AND orgId IS NULL	userId = $USER AND orgId = $ORG	userId = $USER AND accountId = $ACCOUNT
gp_apps_approvals, admin view	Same as member view	orgId = $ORG	accountId = $ACCOUNT

It seems the "account" abstraction might be a little cleaner, but I don't have a strong preference

[MartinKolarik]

Also consider a third role that's completely read-only; orgs that don't want all their members to be able to use credits could change the default from member to this role.

[alexey-yarmosh]

Token/app should both behave as "personal" and stop working on user removal.

1. If a token was created to be used by an org's service:

• On immediate deletion: in the worst case, the service breaks when the user leaves (whether admin or member). A new member needs to generate a new token in advance.
• Without deletion: in the worst case, the user may keep spending the org's credits. A new member needs to generate a new token soon.
  The second option is just less destructive.

There are also notifications. I think the most flexible and relatively easy solution is to make notification settings per org and per user; e.g., I could set one notification config for myself, another for jsDelivr events (which applies only to me), and you could set a different config for jsDelivr events that would apply only to yourself.

2. Agree, I'd just make most org notifications disabled by default, as there may be too many of them.

There's also a second option: introducing an account or owner entity

3. I like an account entity. The extra join to get from account_id to the user/org data is super cheap. And in return, we get a single account_id col, which is much handier to work with than checking both user_id/org_id everywhere. Validation rules and Directus SDK queries also work fine with such construction.
   Updates in tables:

  gp_probes
  userId => account_id

  gp_tokens
  +account_id
  user_created // stays without renaming, now it just means who created the token

  gp_apps_approvals
  +account_id
  user => user_created // same as in gp_tokens

  gp_credits
  user_id => account_id

  gp_credits_deductions
  user_id => account_id

  gp_accounts (new)
  +id
  +user // o2o to directus_users
  +org // o2o to gp_orgs

4. New 'viewer' role. Any admin can set the viewer/member/admin role for any other viewer/member/admin. Automatic GitHub sync only promotes a viewer/member to admin, never demotes back.

[MartinKolarik]

On immediate deletion: in the worst case, the service breaks when the user leaves (whether admin or member). A new member needs to generate a new token in advance.
Without deletion: in the worst case, the user may keep spending the org's credits. A new member needs to generate a new token soon.
The second option is just less destructive.

The problem with the second option is that it's very hard to make it clear, and unless admins actually see and can edit all user tokens, it would be very confusing. It would also be weird that the behavior differs from the apps.

I think we either make it fully user-scoped, which is clear and predictable (each user sees their own tokens, they get deleted on user deletion), or optionally add a switch for "user scoped" vs "org scoped" on token creation. Only admins would be able to create org-scoped; they would be visible to all other admins, and would not be tied to any specific user. But I'd be fine with adding this later and keeping plain user-scoped in the initial version.

[alexey-yarmosh]

Only admins would be able to create org-scoped; they would be visible to all other admins, and would not be tied to any specific user.

Do we want to auth orgs by cookie? I think it should be in sync with tokens. E.g. if members can do an org measurement from globalping.io they can also create org tokens.

[alexey-yarmosh]

Design comment updated. I am planning to implement this in 4 phases so prod can be deployed after each one and never breaks:

1. Org support in Directus. The schema is updated, data is filled by migrations, but the prev user_id cols stay. GitHub sync works.
2. gp-api, gp-auth, and gp-dash switch from user_id to account_id.
3. gp-dash org UI.
4. Cleanup: drop the old cols and dual-read support from extensions.

[MartinKolarik]

Looks good, a few more small notes:

• regular users can't see the org adoption token,
• approval handling will also need to be updated to be bound to the specific account.