Skip to content

5.4.1 Introduction

access is the system responsible for who people are, which Organizations they belong to and what they may do, the access of Moonitoring staff, the audit of privileged actions, and now also the tokens every other system verifies and the webhooks Organizations register. It belongs to the Identity & Access domain of the platform. Every interface it offers follows Choosing an Interface.

Proposal for review

The contracts of this system are a proposal, not confirmed design: endpoints, events and calls were written from the refined requirements, the data model and the flows, and wait for review. What needs a decision is collected in Open Decisions.

5.4.1.1 Host Names

Environment Host
Prod access.moonitoring.com
Stage stage-access.moonitoring.com, behind IAP

The names follow the host name rule; on a developer's computer each service answers on a local port (Running Locally). Each domain below is a path, followed by its version: https://access.moonitoring.com/<domain>/v1.

The client host exposes only /tokens/v1 and /organizations/v1 (decided 2026-11-11), the two domains that installed clients and the apps' servers call on behalf of a person. Staff Access, Audit and Webhooks are reached only through the servers of the Console and of the Organization Dashboard, which call access privately with their own service identity (Network).

5.4.1.2 Domains

Each domain of access is one API, with its own contract and its own version.

  • 5.4.2.1 Organizations

    Organizations (farms, cooperatives, insurers and professionals), their users, memberships, user groups, delegations, cooperative constraints, the global Organization roles and the nations. /organizations/v1

  • 5.4.2.2 Staff Access

    Moonitoring users (people and service accounts), the staff roles and their memberships, and the catalog of capabilities every system publishes. /staff/v1

  • 5.4.2.3 Audit

    The record of every privileged action taken in the Console or through an admin API of any system: who did what, when, with which capability. /audit/v1

  • 5.4.2.4 Tokens

    Sign-in and tokens. /tokens/v1

  • 5.4.2.5 Webhooks

    How the platform's events reach systems outside it (decided 2026-10-30, D9). /webhooks/v1

5.4.1.3 How It Is Used

Organization user

  1. The user signs in through Identity Platform and exchanges the result at /tokens/v1/tokens, choosing the Organization they act as: one of their own, never one reached only through a delegation.
  2. The app calls the Organizations domain to load the current user, their own memberships and the farms that delegated to their active Organization.
  3. Each product system checks the capability against its own membership copy; it does not treat the token as the source of authorization truth. A delegated membership counts only when the token's active Organization is the delegation's delegatee (Choosing the Organization).

Staff member

  1. Identity-Aware Proxy identifies the staff member when they enter the Console.
  2. The Console exchanges that identity for a short-lived staff token through the Tokens domain.
  3. The token identifies the staff member and carries no capabilities; the Console reads them from GET /staff/v1/me, and each target system performs its own capability check against its copy of the staff roles.
  4. A staff service account linked to a Google service account, such as the CI, comes in the same way with that account's Google ID token and gets its own staff token, with no key (Service Accounts That Sign In Through IAP).

Service account

  1. A cooperative system or farm sync client is registered as a service account of its Organization.
  2. The program signs token requests with its registered key and receives a token for its intended calls.
  3. Product systems refresh their local authorization view from Access events or an OrganizationsService snapshot.

Authorization and audit

  1. A product system emits an audit event when a privileged action succeeds.
  2. Access consolidates those events in the Audit domain, recording the actor, the Organization they acted as, the Organization the action concerns, target, capability, and time.
  3. The Console reads the audit trail by target and actor without reading a product system's database.
flowchart LR user{{Organization user}} -->|REST tokens and reads| access[Access API] staff{{Staff member}} -->|REST administration| access dashboard{{Organization Dashboard}} -->|REST| access access -->|gRPC snapshots| systems[Product systems] systems -->|audit events| access
  • Called by: Console (REST); Organization Dashboard (REST); Public readers (REST); ai-gateway (gRPC OrganizationsService); ai-model-platform (gRPC OrganizationsService); farm (gRPC CatalogService, gRPC OrganizationsService); grant (gRPC OrganizationsService); moochat (gRPC CatalogService, gRPC OrganizationsService); news (gRPC OrganizationsService); releases (gRPC OrganizationsService).
  • Calls: every system (gRPC CatalogService).
  • Publishes events consumed by: ai-gateway (5 event types), ai-model-platform (13 event types), farm (14 event types), grant (13 event types), moochat (13 event types), news (2 event types), releases (13 event types).
  • Consumes events of: every system (1 entry), farm (1 entry).
  • Reads no other system's database: everything above goes through a contract on this page or an event.

5.4.1.4 Synchronous Calls Between Systems

OrganizationsService (snapshot of memberships, registration of service accounts) in Organizations; the CatalogService every system implements, which access calls to validate roles, is shown in Staff Access.

5.4.1.5 Events

Events are facts in the past tense, published through the outbox and delivered at least once on the topic access.events.v1; the envelope and the guarantees are in common/v1/events.yaml. Events marked outside reach the Pub/Sub subscriptions an Organization registers in Webhooks, pushed to its HTTPS endpoint or pulled by its own service account.

Publishes (contract: events/v1/asyncapi.yaml):

Event Published when Consumers Outside
organization.created.v1 An Organization became active: created by its owner and approved by staff (D8). farm, moochat, grant, releases, ai-model-platform no
organization.closing.v1 A closure was requested: the Organization is frozen for its grace period. Products stop writes, sync runs and deliveries for it. farm, moochat, grant, releases, ai-gateway, ai-model-platform yes
organization.closure_cancelled.v1 A closure was cancelled during its grace period: the Organization is restored to its previous status. farm, moochat, grant, releases, ai-gateway, ai-model-platform yes
organization.closed.v1 The closure ran: every system deletes or anonymizes what it keeps for the Organization and reports what it kept. farm, moochat, grant, releases, ai-gateway, ai-model-platform yes
organization.updated.v1 An Organization's profile changed: name, fiscal identifier, telephone, timezone, cooperative (after the cooperative accepted the link), owner or status. farm, moochat, grant, releases, ai-model-platform yes
membership.granted.v1 A user received a role in an Organization, directly, through a delegation or through a user group. farm, moochat, grant, releases, ai-model-platform yes
membership.revoked.v1 A membership ended, or a user group stopped giving a role. farm, moochat, grant, releases, ai-model-platform yes
delegation.granted.v1 An Organization delegated a role to another, or changed the role of a delegation. farm, moochat, grant, releases, ai-model-platform yes
delegation.revoked.v1 A delegation ended, with the delegated memberships that depended on it. farm, moochat, grant, releases, ai-model-platform yes
organization_role.updated.v1 A global Organization role was created or its capabilities or priority changed; it reaches every Organization at once. farm, moochat, grant, releases, ai-model-platform no
user.disabled.v1 A user or service account was disabled; its tokens stop being issued. farm, moochat, grant, releases, ai-model-platform no
service_account.registered.v1 A service account was created for an Organization, for example for a farm sync client. farm no
staff_membership.changed.v1 A Moonitoring user received or lost a staff role. moochat, releases, ai-model-platform, ai-gateway, news, farm, grant no
staff_role.updated.v1 A staff role was created or changed. moochat, releases, ai-model-platform, ai-gateway, news, farm, grant no
platform_audit_event.recorded.v1 A privileged action was taken in the Console or through an admin API. Published by the system that made the change, in the same transaction, on its own topic <system>.audit.v1, and consumed by access, which consolidates the audit log. access no

Consumes:

Event From Why
platform_audit_event.recorded.v1 every system Consolidates the audit log it serves in the Audit API, from one subscription on each system's topic <system>.audit.v1, which names the system.
entitlement.*.v1 farm Nothing: access does not check entitlements. Listed for completeness.