> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tallychannel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Access Grants

> How counterparty tenants get read access to identity state.

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:

```bash theme={null}
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](/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](/api-reference/refresh-requests/create) for the API details.