Add or Update Principal
Creates or updates a principal’s roles and flags within the tenant.
Uses PATCH semantics — omitted fields are left unchanged.
Requires account_admin tenancy role.
At least one of tenancy_role, api_functional_role, allow_counterparty_access,
or principal_type must be supplied.
allow_counterparty_access: true may only be set by a caller whose own
principal_type is human. Service account and AI agent callers are rejected
with 422. Revoking (setting false) has no human-caller requirement.
api_functional_role: tenant_owner may only be assigned to principals
with principal_type: human.
Authorizations
Firebase Auth JWT issued by Google Identity Platform.
Obtain a token by signing in at your app domain and calling
firebase.auth().currentUser.getIdToken().
Path Parameters
Tenant identifier.
Principal ID in oidc:{projectId}#{uid} format.
Body
Set to null to remove the tenancy role.
account_admin, billing_admin, account_viewer Set to null to remove the data-access role.
tenant_owner, tenant_admin, tenant_editor, tenant_proposer, tenant_reader Defaults to human on first upsert. Required when registering a service account or AI agent.
human, service_account, ai_agent Grants or revokes counterparty read access for this principal. Setting true requires the caller to have principal_type human.
Response
Principal updated or created.
Account-level role. Controls membership administration (adding/removing principals, billing).
account_admin, billing_admin, account_viewer Data-access role. Controls what the principal may do with subjects and grants. Ranked hierarchy — higher rank implies lower-rank permissions.
tenant_owner, tenant_admin, tenant_editor, tenant_proposer, tenant_reader The kind of principal. Defaults to human. Used to enforce human-only constraints (e.g. tenant_owner, allow_counterparty_access).
human, service_account, ai_agent When true, this principal may call counterparty-facing endpoints (accessible-subjects, grant-path snapshot reads). Defaults to false. May only be set to true by a human account_admin.
active, revoked