Skip to content

6.2.1 Introduction

Organizations & Access describes who uses Moonitoring and what each of them may do. Customers work inside Organizations, farms, cooperatives, insurers and professionals, as users; memberships give them roles, directly or through the user groups they belong to, and entitlements say which models and features their Organization has. Moonitoring staff and internal jobs are Moonitoring users, kept in a separate structure so that running the platform never depends on customer data.

Everything in this domain is owned by the access system, except entitlements and feature usage, which the farm system owns as its Entitlements domain (decided 2026-10-30). Every product references users and Organizations by id and keeps a cached copy of memberships and entitlements, so the same identities, roles and entitlements serve every Moonitoring product.

6.2.1.1 Model notes

Owned by the access system

Owned by the access system, not by a product: identities, Organizations, memberships, global roles and delegations are one system for every Moonitoring product; entitlements and feature usage (Entitlement, FeatureUsage) are owned by the farm system as its Entitlements domain, interface decision D2. A product references User and Organization by id, without foreign keys; rows here are never deleted, and access publishes organization and membership events, and farm its entitlement events, so products keep their copies current. A product reads rights from its own cached copy of memberships and entitlements, never from a token: a token carries the user, the active Organization and its cell only, so a user of a cooperative with thousands of farms gets the same small token as anyone else.

Separation from organization access

Separate from Organization users and Organization access control, for security: no entity here references User, Organization or their roles.

Staff tokens

  • Staff sign in through Identity-Aware Proxy with their Google Workspace account; the access system exchanges that identity for a five-minute token signed by access. Like every token it carries no capabilities. Every system verifies the token with the public keys of access and checks the staff member's capabilities against its own copy of staff roles and memberships, kept current by staff_membership.changed.v1 and staff_role.updated.v1. The Console reads the capabilities of the signed-in staff member from GET /staff/v1/me to show the sections they may use; it never passes capabilities on, and no other system reads the database of access for them.
  • A MoonitoringServiceAccount linked to a Google service account (MoonitoringServiceAccount.google_service_account) signs in the same way, without a key: the CI passes Identity-Aware Proxy on the Console's host with that account's Google ID token, and the Console's server exchanges the assertion for the service account's staff token.

Administrators and separation of duties

  • Administrators come only from a job: the job access-bootstrap-admin of access, run in each environment by a member of infra-admins with their own identity, names or removes an administrator and records who ran it; in prod it needs a second person's approval. No operation grants the Administrators role.
  • Administrators hold every capability so that they can grant the others under the rule of MoonitoringRoleAccessControl.priority, not for daily work: who grants access is not who works on the data. Releases, signing keys, closures and erasures need two people.

6.2.1.2 Diagram

Entities of this domain, their subtypes and the references between them. References to other domains are listed on each entity page.

classDiagram class User class Person class ServiceAccount class Organization class Cooperative class Farm class Insurer class Professional class Nation class OrganizationAccessControlMembership class DirectMembership class DelegatedMembership class OrganizationRoleAccessControl class OrganizationDelegationMembership class CooperativeConstraint class UserGroup class UserGroupMembership class UserGroupRoleAssignment class DirectGroupRole class DelegatedGroupRole class Entitlement class FeatureUsage class OrganizationClosure class OrganizationInvitation class OrganizationJoinLink class OrganizationJoinRequest class RefreshToken class WebhookSubscription class FailedDelivery class MoonitoringAccessControlMembership class MoonitoringRoleAccessControl class MoonitoringUser class MoonitoringPerson class MoonitoringServiceAccount class PlatformAuditEvent User <|-- Person User <|-- ServiceAccount Organization <|-- Cooperative Organization <|-- Farm Organization <|-- Insurer Organization <|-- Professional OrganizationAccessControlMembership <|-- DirectMembership OrganizationAccessControlMembership <|-- DelegatedMembership UserGroupRoleAssignment <|-- DirectGroupRole UserGroupRoleAssignment <|-- DelegatedGroupRole MoonitoringUser <|-- MoonitoringPerson MoonitoringUser <|-- MoonitoringServiceAccount ServiceAccount --> Organization : organization ServiceAccount --> Person : owner Organization --> Person : owner Organization --> DirectMembership : members Farm --> Cooperative : cooperative OrganizationAccessControlMembership --> User : user OrganizationAccessControlMembership --> User : assigner OrganizationAccessControlMembership --> User : revoked_by DirectMembership --> Organization : organization DirectMembership --> OrganizationRoleAccessControl : role DelegatedMembership --> OrganizationDelegationMembership : delegation OrganizationDelegationMembership --> Organization : delegatee OrganizationDelegationMembership --> OrganizationRoleAccessControl : role OrganizationDelegationMembership --> Organization : delegator OrganizationDelegationMembership --> User : created_by OrganizationDelegationMembership --> User : revoked_by CooperativeConstraint --> Cooperative : cooperative UserGroup --> Organization : organization UserGroup --> User : created_by UserGroup --> User : archived_by UserGroupMembership --> UserGroup : group UserGroupMembership --> User : user UserGroupMembership --> User : assigner UserGroupMembership --> User : revoked_by UserGroupRoleAssignment --> UserGroup : group UserGroupRoleAssignment --> User : assigner UserGroupRoleAssignment --> User : revoked_by DirectGroupRole --> OrganizationRoleAccessControl : role DelegatedGroupRole --> OrganizationDelegationMembership : delegation Entitlement --> Organization : organization Entitlement --> MoonitoringUser : granted_by OrganizationClosure --> Organization : organization OrganizationInvitation --> Organization : organization OrganizationInvitation --> OrganizationRoleAccessControl : role OrganizationInvitation --> UserGroup : groups OrganizationInvitation --> User : invited_by OrganizationInvitation --> Person : accepted_by OrganizationInvitation --> User : revoked_by RefreshToken --> Person : user RefreshToken --> Organization : organization OrganizationJoinLink --> Organization : organization OrganizationJoinLink --> OrganizationRoleAccessControl : role OrganizationJoinLink --> UserGroup : groups OrganizationJoinLink --> User : created_by OrganizationJoinLink --> User : revoked_by OrganizationJoinRequest --> OrganizationJoinLink : link OrganizationJoinRequest --> Person : person OrganizationJoinRequest --> User : decided_by WebhookSubscription --> Organization : organization WebhookSubscription --> User : created_by FailedDelivery --> WebhookSubscription : subscription PlatformAuditEvent --> MoonitoringUser : actor PlatformAuditEvent --> User : user PlatformAuditEvent --> Organization : organization PlatformAuditEvent --> Organization : acting_organization FeatureUsage --> Organization : organization FeatureUsage --> MoonitoringUser : moonitoring_user MoonitoringAccessControlMembership --> MoonitoringUser : user MoonitoringAccessControlMembership --> MoonitoringUser : assigner MoonitoringAccessControlMembership --> MoonitoringRoleAccessControl : role MoonitoringAccessControlMembership --> MoonitoringUser : revoked_by MoonitoringServiceAccount --> MoonitoringPerson : owner Person --> Nation : telephone_number Organization --> Nation : fiscal_national_identifier Organization --> Nation : telephone_number

Not shown, because they reference nothing in the diagram: CapabilityCatalog.

6.2.1.3 Entities

  • User: A User is anyone who acts inside an Organization: a person or a service account, a program that calls our API on the Organization's behalf.
  • Organization: An Organization is a customer body that uses Moonitoring, and always exactly one of four types: a farm that keeps animals, a cooperative that groups farms, an insurer that covers them, or a professional, such as a veterinary practice, an advisor or a laboratory, that farms share data with.
  • Nation: Reference list of nations.
  • OrganizationAccessControlMembership: Grants a user a role inside an Organization.
  • OrganizationRoleAccessControl: A named bundle of capabilities that can be given to the users of any Organization.
  • OrganizationDelegationMembership: Lets one Organization act on behalf of another with a given role, for example a cooperative managing the data of one of its farms, or an insurer reading the herds it covers.
  • CooperativeConstraint: A rule that a cooperative imposes on its farms, for example a minimum number of cows in lactation.
  • UserGroup: A set of users of one Organization that receives roles as a whole, like a group in Google Workspace.
  • UserGroupMembership: Puts one user in one group for a period.
  • UserGroupRoleAssignment: Gives a role to a group, either in its own Organization or, through a delegation, in the delegator.
  • Entitlement: What an Organization has bought or been granted: a model, a product feature, a plan.
  • FeatureUsage: How much of a metered feature an Organization has used in a period, for example MooChat tokens this month.
  • OrganizationClosure: Closes an Organization the way cloud providers delete a project: the request starts a grace period of 30 days during which the Organization is frozen but can still be restored, and at its end the closure runs once and cannot be undone.
  • OrganizationInvitation: How a person joins an Organization, the way Google Workspace or GitHub do it: a member invites an e-mail address with a role and, if they like, groups; the person accepts, signs in or signs up, and only then do their Person and their direct membership exist.
  • OrganizationJoinLink: A link an Organization shares so that people join by themselves, like the invite links of Slack or Discord: whoever opens it signs in or registers and becomes a member with the link's role and groups, at once or after an approval.
  • OrganizationJoinRequest: A person who used a join link that requires an approval.
  • RefreshToken: One link of a refresh token chain.
  • CapabilityCatalog: What a system published as its capabilities and features, version by version.
  • WebhookSubscription: How an Organization receives events outside the platform: a Pub/Sub subscription on platform.external.v1, filtered by the Organization and the event types it chose, pushed to its HTTPS address with a Google-signed token or pulled by its own Google service account.
  • FailedDelivery: An event a subscription could not deliver after Pub/Sub's attempts.
  • MoonitoringAccessControlMembership: Grants a Moonitoring user a role on the platform.
  • MoonitoringRoleAccessControl: A named bundle of platform capabilities for Moonitoring users, ordered by priority like organization roles.
  • MoonitoringUser: Anyone who acts for Moonitoring itself: a person on the team, or a service account such as model training, the continuous integration (CI) pipeline that builds our software, or an internal job.
  • PlatformAuditEvent (immutable): Who did what, and when, in the Console and through every admin API: one immutable row per important action, written in the same transaction as the change it records, with the capability that allowed it and the fields that changed.