iceberg-subzero 0.2.1

Python client for the Subzero tokenization vault

Subzero Python SDK

Thin Python client for the Subzero tokenization vault.

Configure entity types, API keys, and reveal policies in the dashboard first. This SDK is for server-side vault operations only.

See docs/vault-sdk.md for the full integration guide.

Install

pip install iceberg-subzero

Quick start

from subzero import SubzeroClient

client = SubzeroClient(
    tokenize_key="sz_live_...",   # tokenize + search + batch
    reveal_key="sz_live_...",     # reveal
)
client.ready()

token = client.tokenize("SSN", "123-45-6789")
found = client.search("SSN", "123-45-6789")   # blind index lookup
value = client.reveal(token)

Or from environment variables:

client = SubzeroClient.from_env()  # SUBZERO_API_KEY or split keys; SUBZERO_BASE_URL

A single api_key works when one key has both scopes (e.g. admin):

client = SubzeroClient(api_key="sz_live_...")

API key scopes

Scope	SDK methods
tokenize	tokenize, search, tokenize_batch
reveal	reveal (requires a matching reveal policy in the dashboard)
admin	All of the above (bypasses reveal policy)

Use separate tokenize_key and reveal_key in production for least privilege.

Batch tokenize

For ETL pipelines. Max 100 items per API request; the SDK auto-chunks larger lists.

from subzero import TokenizeBatchItem, TokenizeBatchContext

results = client.tokenize_batch(
    [
        TokenizeBatchItem(index=0, entity_type="SSN", value="123-45-6789"),
        TokenizeBatchItem(index=1, entity_type="SSN", value="987-65-4321"),
    ],
    context=TokenizeBatchContext(source="dbt", pipeline_id="contacts"),
)

for item in results:
    if item.ok:
        print(item.index, item.token)
    else:
        print(item.index, item.error)  # per-item errors do not fail the batch

Example

With the API running and keys configured in the dashboard:

export SUBZERO_TOKENIZE_API_KEY=sz_live_...
export SUBZERO_REVEAL_API_KEY=sz_live_...
python examples/vault_demo.py

Tests

pytest

PyPI

Local editable install only for now.