Quickstart - Tally Platform

This guide walks through the minimum path to write and read identity state. You’ll need a valid Bearer token — see Authentication first.

Create a tenant

A tenant is the accountable owner of subjects. Create one with an ID of your choice.

curl -X POST https://tally-platform-api-iikaevm4pq-ue.a.run.app/v1/tenants \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "acme-corp",
    "display_name": "Acme Corporation"
  }'

The calling principal is automatically added as account_admin (tenancy role) and tenant_admin (data-access role). See Principals & Roles for what each means.

Write initial identity state

Create the first snapshot for a subject. You must supply a complete entityStateEnvelopeV1 — the platform stores it verbatim.

curl -X POST https://tally-platform-api-iikaevm4pq-ue.a.run.app/v1/tenants/acme-corp/entity-states \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "envelope_version": "entity_state_envelope_v1",
    "snapshot_id": "018f2e3a-1234-7000-8000-abcdef012345",
    "snapshot_version": 1,
    "generated_at": "2026-06-10T12:00:00Z",
    "subject": {
      "subject_type": "organization",
      "subject_id": "subj-acme-001"
    },
    "attributes": {
      "legal": {
        "legal_name": "Acme Corporation",
        "status": "active"
      },
      "jurisdiction": {
        "country_of_incorporation": "US",
        "region_of_incorporation": "US-DE"
      }
    },
    "evidence": [],
    "audit": {
      "created_by": "oidc:your-project#your-uid",
      "created_at": "2026-06-10T12:00:00Z",
      "source": "manual"
    }
  }'

The response returns snapshot_id, snapshot_version: 1, and the computed envelope_hash.

Read the latest snapshot

curl https://tally-platform-api-iikaevm4pq-ue.a.run.app/v1/tenants/acme-corp/subjects/organization/subj-acme-001/snapshots/latest \
  -H "Authorization: Bearer $TOKEN"

Propose and apply an update

Updates use RFC 6902 JSON Patch. First propose, then apply.

# Propose
curl -X POST https://tally-platform-api-iikaevm4pq-ue.a.run.app/v1/tenants/acme-corp/subjects/organization/subj-acme-001/updates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "subj-acme-001",
    "subject_type": "organization",
    "base_snapshot_version": 1,
    "patch_ops": [
      {
        "op": "add",
        "path": "/attributes/identifiers",
        "value": [
          {
            "identifier_type": "lei",
            "identifier_value": "549300ABCDEF123456XX"
          }
        ]
      }
    ]
  }'

# Apply (use update_id from the propose response)
curl -X POST https://tally-platform-api-iikaevm4pq-ue.a.run.app/v1/tenants/acme-corp/subjects/organization/subj-acme-001/updates/{update_id}/apply \
  -H "Authorization: Bearer $TOKEN"

The apply creates snapshot_version: 2.

Verify snapshot integrity

Pass verify=hash on any snapshot read to check the RFC 8785 hash:

curl "https://tally-platform-api-iikaevm4pq-ue.a.run.app/v1/tenants/acme-corp/subjects/organization/subj-acme-001/snapshots/latest?verify=hash" \
  -H "Authorization: Bearer $TOKEN"

The response includes a verification block with valid: true when the stored hash matches the freshly computed one.

Next steps

Concepts: Snapshots — understand the immutable ledger model
Concepts: Access Grants — share read access with counterparties
Concepts: Verification — hash and chain proof details

​Next steps

Next steps