Accounts Service Access Rules by Actor

UserAccounts and Tenants have special access control characteristics because they cannot be strictly scoped by the current session tenant.

Overview

This document describes the access rules enforced by the Accounts component’s service layer. It follows the structure and terminology of the platform’s Access Rules for UserAccounts and Tenants, but records the behavior implemented in this repository.

The four actor-facing services are:

• UserAccountService
• TenantService
• AgentForService, which manages a user’s affiliation with a tenant
• InvitationService

The rules apply to single-record reads by entity or record ID, historical reads, list queries, and mutations exposed by the corresponding data-authority endpoints unless an operation is identified as internal.

Shared Constraints

• Onboarding happens through the HubSpot or Arda Cloud signup page and access to the service is granted through a system flow.
• User-account creation is a service-driven onboarding operation. A human actor cannot directly create a UserAccount through an API call.
• Tenant creation is service-driven. It normally occurs as part of user onboarding.
• Tenant users are added through invitations.
• Bulk create and bulk update are not implemented by any of the four actor-facing services.
• Deleting a UserAccount or tenant also deletes all of its affiliations.
• An active tenant administrator cannot demote or remove their own administrator affiliation if that would leave the tenant without another active administrator.
• A user cannot remove their own affiliation if it would leave the tenant without another active user.

End Users

An End User is a tenant-scoped user with the USER role. An End User:

• Can view all UserAccount records associated with the current tenant, including their history.
• Can view all tenants they belong to, including their history.
• Can view their own tenant affiliations and every affiliation in the current tenant.
• Can update their own UserAccount identity, except for the email address, plus their settings. They cannot update their subscription.
• Can update the non-role, non-status fields of their own affiliation.
• Can leave a tenant when another active user remains.
• Can invite a user to the current tenant when the invitee is not already affiliated with it.
• Can view and delete invitations in the current tenant. When they are not the invitee, they can also resend, cancel, or archive them subject to the invitation’s current status.
• Can view an invitation addressed to their email address and can accept or reject it while it is pending. Accepting the invitation creates an active USER affiliation.

Tenant Administrators

A Tenant Administrator has all End User permissions. In addition, for the tenant they administer, a Tenant Administrator:

• Can update the tenant’s name, company information, and settings, but cannot change its subscription plan.
• Can update another user’s affiliation, including its status and settings.
• Can promote a USER to ADMIN.
• Can demote an ADMIN to USER when another active administrator will remain.
• Can suspend or revoke an affiliation without changing its role.
• Can evict a USER by deleting their affiliation.
• Can delete or suspend their own affiliation only when another active administrator remains.

SaaS Administrators

A SaaS Administrator is a human user whose account has isSaasAdmin = true. A SaaS Administrator:

• Can view every UserAccount, tenant, and affiliation, including lists and history.
• Can update their own UserAccount using the End User field restrictions.
• Can promote another account to SaaS administrator.
• Can demote their own or another SaaS administrator while another SaaS administrator will remain.
• Can update any tenant’s name, company information, plan, and settings.
• Can directly create an affiliation.
• Can update any affiliation and promote a USER to ADMIN in any tenant.
• Can demote an ADMIN in any tenant when another active administrator will remain.
• Can delete any affiliation, including the last ADMIN affiliation in a tenant.
• Can delete any UserAccount; the deletion cascades to all of the user’s affiliations.
• Can delete any tenant; the deletion cascades to all affiliations in that tenant.
• Can view an invitation addressed to their email address and accept or reject it while operating globally. They must enter a tenant scope to create invitations or manage invitations addressed to other users; list, history, and deletion remain limited to the selected tenant scope.
• When they are not the invitee, they can resend, cancel, or archive any accessible invitation subject to its current status. They can accept or reject an invitation only when they are its invitee.

Global Users

A Global User is a human user operating without a current tenant scope and without SaaS-administrator privileges. A Global User:

• Can update their own UserAccount, even though the API does not permit them to read or list UserAccount records in global scope.
• Can view an invitation addressed to their email address and can accept or reject it while it is pending.

Service Users

A Service User is a configured machine-to-machine account. An ordinary Service User:

• Can view every tenant and affiliation, including lists and history.
• Can create a UserAccount through the onboarding operation, which also creates the required tenant and affiliation records.
• Can create a tenant through the service-authorized API operation.
• Can update only the plan of any tenant; all other tenant fields are preserved.
• Can update any affiliation without changing its role.

A service account may itself be configured with isSaasAdmin = true. It remains a ServiceActor, so operations that distinguish machine and human actors do not necessarily grant it every permission listed for a human SaaS Administrator.

Differences From the Functional Model

The referenced functional model is broader than the current implementation in several places:

• The model says that tenant administrators may change a tenant’s subscription plan. TenantService currently allows only a SaaS admin or service actor to change plan.