Access Grants

Nothing in Tally is shared by default. A grant is an explicit, scoped permission that one tenant issues to another to read a specific subject’s identity state.

Grant model

Grants are subject-scoped. The granting tenant must own the subject. Grants can expire or be revoked at any time.

Field	Description
`grantor_tenant_id`	The owning tenant issuing the grant.
`grantee_tenant_id`	The counterparty tenant receiving access.
`subject_type` + `subject_id`	The specific subject being shared.
`scopes`	What the grantee can do (see below).
`expires_at`	Optional expiry. Null = does not expire.

Scopes

Scope	What it allows
`read_latest`	`GET .../snapshots/latest`
`read_lineage`	`GET .../snapshots` (history) and chain-proof
`read_snapshot_by_id`	`GET .../snapshots/{snapshot_id}`
`read_diff`	`GET .../diff`

Scopes are additive — a grant can carry any combination of them.

Accessible subjects

A grantee tenant can call GET /v1/tenants/{tenant_id}/accessible-subjects to see all subjects shared with them across all grantors, along with the latest snapshot header for each (if read_latest is held). Grants operate at the tenant level, but counterparty read access is additionally gated at the principal level. The calling principal must have allow_counterparty_access: true set on their access record. This flag defaults to false — receiving a grant does not automatically grant access to any individual within the grantee tenant. An account_admin enables the flag per-principal:

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 '{ "allow_counterparty_access": true }'

The token making this call must belong to a human account_admin — service accounts and AI agents cannot expand counterparty visibility. See Authentication for details on principal_type.

Revocation

Call POST /v1/tenants/{tenant_id}/grants/{grant_id}/revoke. Access is removed immediately. Grantee read requests fail with 403 after revocation.

Refresh requests

When a grantee needs the owner to update or confirm specific attributes, they submit a refresh request. The owner can fulfill it by pointing to an existing snapshot or by applying a new update first. See Refresh Requests for the API details.

Overview

Concepts

Grant model

Scopes

Accessible subjects

Revocation

Refresh requests

​Grant model

​Scopes

​Accessible subjects

​Revocation

​Refresh requests

Grant model

Scopes

Accessible subjects

Revocation

Refresh requests