Principals & Roles

Access in Tally Platform is controlled by two independent role dimensions on each principal’s membership record. Both must be present for a principal to act within a tenant.

Two-layer role model

Account roles (`tenancy_role`)

Account roles govern tenant administration — adding and removing members, managing billing. They say nothing about what a principal can do with subjects or grants.

Role	What it allows
`account_admin`	Manage all principal access records. At least one active `account_admin` must always remain on a tenant.
`billing_admin`	Manage billing and subscription details.
`account_viewer`	Read tenant membership and billing information.

Account roles are independent capabilities, not a ranked hierarchy.

Data-access roles (`api_functional_role`)

Data-access roles control what a principal can do with subjects belonging to (or accessible via grants held by) their own tenant. These form a ranked hierarchy — a higher rank includes all permissions of lower ranks.

Role	Rank	What it allows
`tenant_owner`	5	Permanent accountability anchor for the tenant’s subjects. Can do everything `tenant_admin` can. May only be held by a `human` principal.
`tenant_admin`	4	Full subject read/write, grant management, refresh requests.
`tenant_editor`	3	Create and apply updates; read all subject data.
`tenant_proposer`	2	Propose updates; read all subject data.
`tenant_reader`	1	Read subject data only. Minimum role for counterparty access.

A principal may hold both a tenancy_role and an api_functional_role simultaneously, or just one, depending on their responsibilities.

The `tenant_owner` role

tenant_owner is the accountability anchor for the Tenant↔Subject relationship. It is not simply a higher-privilege version of tenant_admin — it carries legal and compliance significance and may only be held by a human principal. Ownership of a subject (the Tenant↔Subject pairing) is permanent and structural. What transfers via the ownership transfer offer flow is the tenant_owner role within the owning tenant — not the subject itself.

Counterparty access (`allow_counterparty_access`)

Grants operate at the tenant level, but accessing counterparty subjects also requires a per-principal flag. A principal with allow_counterparty_access: false (the default) receives 403 on counterparty endpoints even if their tenant holds active grants. The flag is set by an account_admin and may only be enabled by a human caller. See Access Grants for the full workflow.

Setting roles

All role and flag management goes through PUT /v1/tenants/{tenant_id}/principals/{principal_id}. The endpoint uses PATCH semantics — omitted fields are unchanged.

# Add a service account with read-only data access
curl -X PUT https://tally-platform-api-iikaevm4pq-ue.a.run.app/v1/tenants/{tenant_id}/principals/{principal_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_functional_role": "tenant_reader",
    "principal_type": "service_account"
  }'

# Grant counterparty read access to a human analyst (must be called by a human account_admin)
curl -X PUT https://tally-platform-api-iikaevm4pq-ue.a.run.app/v1/tenants/{tenant_id}/principals/{principal_id} \
  -H "Authorization: Bearer $HUMAN_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "allow_counterparty_access": true }'

See Authentication for details on principal_type and human-only constraints.

Overview

Concepts

Two-layer role model

Account roles (`tenancy_role`)

Data-access roles (`api_functional_role`)

The `tenant_owner` role

Counterparty access (`allow_counterparty_access`)

Setting roles

​Two-layer role model

​Account roles (tenancy_role)

​Data-access roles (api_functional_role)

​The tenant_owner role

​Counterparty access (allow_counterparty_access)

​Setting roles

Two-layer role model

Account roles (`tenancy_role`)

Data-access roles (`api_functional_role`)

The `tenant_owner` role

Counterparty access (`allow_counterparty_access`)

Setting roles