Grants API: Share Subject Access Across Tenants

A grant is a scoped, revocable permission that lets one tenant (the grantee) read identity data for a subject owned by another tenant. You control exactly which operations the grantee may perform by specifying one or more data scopes on the grant. Grants power the multi-tenant data-sharing model at the heart of Tally — for example, a lender sharing a borrower’s KYC snapshot with a compliance counterparty, or a platform sharing entity data with a downstream partner.

Create a grant

POST /v1/tenants/:tenant_id/grants Creates a new active grant giving grantee_tenant_id access to one of your subjects with the specified scopes. Requires the tenant_admin role. Your tenant must be the owner of the subject.

Path parameters

tenant_id

string

required

The ID of your (the owner) tenant.

Body parameters

subject_type

string

required

The type of subject being shared. Must be entity or individual.

subject_id

string

required

The identifier of the subject being shared.

grantee_tenant_id

string

required

The ID of the tenant you are granting access to. Must refer to an existing tenant.

scopes

array of strings

required

The data operations the grantee is permitted to perform. Must be a non-empty array containing one or more of the following values:

Scope	Permits
`read_latest`	Read the latest snapshot for the subject.
`read_lineage`	Walk the full snapshot history (parent chain).
`read_snapshot_by_id`	Fetch any specific snapshot by ID.
`read_diff`	Compute a diff between any two snapshots.

expires_at

string (ISO 8601)

An optional expiry timestamp after which the grant is no longer valid. Omit for a grant that does not expire.

Response

201 Created — the new grant object.

Show Grant object fields

grant_id

string (UUID)

Unique identifier for this grant.

subject_type

string

The type of subject covered by this grant.

subject_id

string

The identifier of the subject covered by this grant.

grantee_tenant_id

string

The tenant that received access.

scopes

array of strings

The scopes included in this grant.

status

string

"active" when first created. Changes to "revoked" after a revoke call.

expires_at

string | null

ISO 8601 expiry timestamp, or null if the grant does not expire.

created_at

string (ISO 8601)

When the grant was created.

Error responses

Status	Code	Meaning
`403`	`forbidden`	Your tenant is not the owner of the subject.
`409`	`conflict`	An active grant already exists for this `(subject, grantee_tenant)` pair, or the `grantee_tenant_id` does not exist.

List grants on a subject

GET /v1/tenants/:tenant_id/subjects/:subject_type/:subject_id/grants Returns all grants (active, revoked, and expired) on a specific subject that your tenant owns. Requires the tenant_admin role. Your tenant must be the owner of the subject.

Path parameters

tenant_id

string

required

The ID of your (the owner) tenant.

subject_type

string

required

Must be entity or individual.

subject_id

string

required

The identifier of the subject.

Response

200 OK

{
  "items": [
    {
      "grant_id": "b3c4d5e6-0000-0000-0000-aabbccdd1122",
      "subject_type": "entity",
      "subject_id": "ent_7f3a1b2c",
      "grantee_tenant_id": "partner-bank",
      "scopes": ["read_latest", "read_diff"],
      "status": "active",
      "expires_at": "2025-01-01T00:00:00.000Z",
      "created_at": "2024-06-01T12:00:00.000Z"
    }
  ]
}

Revoke a grant

POST /v1/tenants/:tenant_id/grants/:grant_id/revoke Immediately revokes an active grant. After revocation the grantee loses all access to the subject. Requires the tenant_admin role. Your tenant must be the owner of the subject covered by the grant.

Path parameters

tenant_id

string

required

The ID of your (the owner) tenant.

grant_id

string (UUID)

required

The ID of the grant to revoke.

Response

200 OK — the updated grant object with status: "revoked" and a revoked_at timestamp.

{
  "grant_id": "b3c4d5e6-0000-0000-0000-aabbccdd1122",
  "status": "revoked",
  "revoked_at": "2024-06-15T09:22:00.000Z"
}

Error responses

Status	Code	Meaning
`404`	`not_found`	No grant exists with this `grant_id`.
`409`	`conflict`	The grant is not active (already revoked or expired).

List accessible subjects

GET /v1/tenants/:tenant_id/accessible-subjects Returns all subjects your tenant can access via active grants. Each item includes the latest snapshot metadata and a provenance summary so you can quickly assess data freshness without fetching full snapshots. Requires at least the tenant_reader role.

Path parameters

tenant_id

string

required

The ID of your (the grantee) tenant.

Query parameters

limit

integer

Number of results per page. Between 1 and 200. Defaults to 50.

cursor

string

Opaque pagination cursor from the previous response’s page.next_cursor.

Response

200 OK

Show Response fields

items

array

Array of accessible subject objects. Each item contains:

subject_type — "entity" or "individual"
subject_id — the subject identifier
scopes — the scopes available to your tenant for this subject
expires_at — when the grant expires, or null
access_via — always "grant" for counterparty access
identity_summary.display_name — a human-readable name when available
latest_snapshot.snapshot_id — ID of the latest snapshot
latest_snapshot.snapshot_version — version number of the latest snapshot
latest_snapshot.generated_at — when the latest snapshot was generated
provenance_summary.evidence_count — number of evidence items attached
provenance_summary.has_attribute_paths — whether attribute-level provenance is present
provenance_summary.has_audit — whether an audit trail is attached

page.limit

integer

The limit used for this page.

page.next_cursor

string | null

Pass this value as cursor to fetch the next page. null when there are no more results.

{
  "items": [
    {
      "subject_type": "entity",
      "subject_id": "ent_7f3a1b2c",
      "scopes": ["read_latest", "read_diff"],
      "expires_at": "2025-01-01T00:00:00.000Z",
      "access_via": "grant",
      "identity_summary": {
        "display_name": "Acme Trading Ltd"
      },
      "latest_snapshot": {
        "snapshot_id": "e9d8c7b6-1234-5678-abcd-000011112222",
        "snapshot_version": 5,
        "generated_at": "2024-06-10T14:00:00.000Z"
      },
      "provenance_summary": {
        "evidence_count": 3,
        "has_attribute_paths": true,
        "has_audit": false
      }
    }
  ],
  "page": {
    "limit": 50,
    "next_cursor": null
  }
}

Full lifecycle example

curl -X POST https://api.tally.so/v1/tenants/acme-corp/grants \
  -H "Authorization: Bearer $TALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_type": "entity",
    "subject_id": "ent_7f3a1b2c",
    "grantee_tenant_id": "partner-bank",
    "scopes": ["read_latest", "read_diff"],
    "expires_at": "2025-01-01T00:00:00.000Z"
  }'
# → 201 { "grant_id": "b3c4d5e6-...", "status": "active", ... }

Use GET /v1/tenants/:tenant_id/accessible-subjects from the grantee’s token to verify the grant is visible before directing your counterparty to start making data requests. Once you revoke, the subject will disappear from their accessible-subjects list on the next call.

​Create a grant

​Path parameters

​Body parameters

​Response

​Error responses

​List grants on a subject

​Path parameters

​Response

​Revoke a grant

​Path parameters

​Response

​Error responses

​List accessible subjects

​Path parameters

​Query parameters

​Response

​Full lifecycle example

Create a grant

Path parameters

Body parameters

Response

Error responses

List grants on a subject

Path parameters

Response

Revoke a grant

Path parameters

Response

Error responses

List accessible subjects

Path parameters

Query parameters

Response

Full lifecycle example