SDK Python Integration

pip install veilio-sdk

import os
from veilio_sdk import VeilioClient

veilio = VeilioClient(
    api_key=os.getenv("VEILIO_API_KEY"),
    base_url=os.getenv("VEILIO_BASE_URL", "https://app.veilio.fr/api"),
)

def create_customer(email: str):
    result = veilio.tokenize(
        data=email,
        type="email",
    )

    # Store token in your DB, not the raw email.
    return {"email_token": result["token"]}

def send_welcome_email(email_token: str):
    original = veilio.detokenize(
        token=email_token,
        reason="Send welcome email",
    )
    return original["data"]

# Call when a user requests account deletion (GDPR right to erasure)
def delete_user_data(email_token: str):
    veilio.shred_token(
        token=email_token,
        reason="GDPR - user deletion request",
    )

veilio = VeilioClient(
    api_key: str,              # Required — your Veilio API key
    base_url: str = "https://app.veilio.fr/api",
    timeout: int = 30,         # Request timeout in seconds
    max_retries: int = 3,      # Retries on rate limits / network errors
)

veilio = VeilioClient(
    api_key=os.environ["VEILIO_API_KEY"],
    base_url="https://your-domain.com/api",
)

result = veilio.tokenize(
    data="john@example.com",
    type="email",                          # Optional: email, phone, iban, etc.
    metadata={"source": "signup"},         # Optional
    retention={                            # Optional — automatic shredding
        "ttlDays": 30,                     # Shred after N days
        # or "retentionUntil": "2026-12-31T2359.000Z"
    },
)

phone = veilio.tokenize(
    data="0612345678",
    type="phone",
    mode="fpt",
    entity_id="BP10042",
)
# phone["token"] == "0600000000"

# Returns: {"token": str, "createdAt": str, "retentionUntil": str | None}

result = veilio.tokenize_bulk(
    [
        {"data": "john@example.com", "type": "email", "mode": "fpt"},
        {"data": "+33612345678", "type": "phone", "mode": "fpt", "retention": {"ttlDays": 365}},
        {"data": "Ada Lovelace", "type": "firstName"},
    ],
    entity_id="BP10042",
)
# result["tokens"][0]["token"] == "00000000@example.com"
# result["tokens"][1]["token"] == "0600000000"

# Returns: {"tokens": [...], "summary": {"total", "success", "failed"}, "errors"?, "createdAt"}

result = veilio.detokenize(
    token="tok_abc123...",
    reason="Send email",           # Optional — logged for audit
    username="alice.dupont",       # Optional — end-user of YOUR app (AccessLog.actorUsername)
)

phone = veilio.detokenize(
    token="0600000000",
    entity_id="BP10042",
    reason="Partner screen",
)

# Returns: {"data": str, "accessedAt": str}

result = veilio.detokenize_bulk(
    [
        {"token": "00000000@example.com"},
        {"token": "0600000000"},
        {"token": "000000000", "type": "siren"},
        {"token": "tok_def456...", "reason": "Profile view"},
    ],
    entity_id="BP10042",
    reason="Profile view",  # Optional — one audit log line for the whole batch
    username="alice.dupont",
)

# Returns: {"results": [...], "summary": {...}, "errors"?, "accessedAt"}

result = veilio.shred_token(
    token="tok_abc123...",
    reason="GDPR delete request",  # Optional
)

# Returns: {"token": str, "shreddedAt": str}

import json

result = veilio.tokenize_format(
    data=json.dumps({"email": "john@example.com", "phone": "+33612345678"}),
    format="json",  # Optional — auto-detected if omitted ("json", "csv", "sql")
    options={
        "fields": ["email"],              # Optional — tokenize only specific paths
        "retention": {"ttlDays": 365},    # Optional
        "csv": {                          # CSV-specific options
            "delimiter": ",",
            "hasHeaders": True,
        },
    },
)

# Returns: {"format", "tokenizedData", "tokens": [{"path", "token", "type?"}], "summary", "metadata"?}

result = veilio.detokenize_format(
    tokenized_data='{"email": "tok_abc123..."}',
    format="json",
    tokens=[{"path": "email", "token": "tok_abc123..."}],
)

# Returns: {"format", "detokenizedData", "summary": {"tokensProcessed"}}

fields = [
    {"data": "alice@example.com", "type": "email"},
    {"data": "+33612345678", "type": "phone"},
]

bulk = veilio.tokenize_bulk(fields=fields)

if bulk["summary"]["failed"] > 0:
    print("Partial failure:", bulk.get("errors", []))

tokens = [
    {"token": t["token"], "reason": "Migration verification"}
    for t in bulk["tokens"]
]
values = veilio.detokenize_bulk(tokens=tokens)

# Automatic shredding after 30 days
tokenized = veilio.tokenize(
    data="delete-me@example.com",
    type="email",
    retention={"ttlDays": 30},
)

# Immediate shredding (irreversible)
veilio.shred_token(
    token=tokenized["token"],
    reason="User deletion request",
)

from veilio_sdk import (
    VeilioClient,
    VeilioError,
    AuthenticationError,
    RateLimitError,
    PlanLimitError,
    TokenShreddedError,
)

try:
    result = veilio.detokenize(token="tok_abc123...", reason="Support case")
except AuthenticationError as e:
    print(f"Auth error: {e}")
except RateLimitError as e:
    print(f"Rate limit reached, retry after: {getattr(e, 'retry_after', None)}s")
except PlanLimitError as e:
    print(f"Plan limit exceeded: {e}")
except TokenShreddedError:
    print("Token has been shredded and cannot be detokenized.")
except VeilioError as e:
    print(f"Veilio API error [{e.code}]: {e.message}")