> ## 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.

# Quickstart

> Create a tenant, write your first identity state, and read it back in five steps.

This guide walks through the minimum path to write and read identity state. You'll need a valid Bearer token — see [Authentication](/authentication) first.

<Steps>
  <Step title="Create a tenant">
    A tenant is the accountable owner of subjects. Create one with an ID of your choice.

    ```bash theme={null}
    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](/concepts/principals) for what each means.
  </Step>

  <Step title="Write initial identity state">
    Create the first snapshot for a subject. You must supply a complete `entityStateEnvelopeV1` — the platform stores it verbatim.

    ```bash theme={null}
    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`.
  </Step>

  <Step title="Read the latest snapshot">
    ```bash theme={null}
    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"
    ```
  </Step>

  <Step title="Propose and apply an update">
    Updates use RFC 6902 JSON Patch. First propose, then apply.

    ```bash theme={null}
    # 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`.
  </Step>

  <Step title="Verify snapshot integrity">
    Pass `verify=hash` on any snapshot read to check the RFC 8785 hash:

    ```bash theme={null}
    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.
  </Step>
</Steps>

## Next steps

* [Concepts: Snapshots](/concepts/snapshots) — understand the immutable ledger model
* [Concepts: Access Grants](/concepts/grants) — share read access with counterparties
* [Concepts: Verification](/concepts/verification) — hash and chain proof details