veilio-sdk

Official Python SDK for Veilio - Data tokenization and cyber-resilience API.

Installation

pip install veilio-sdk

Quick Start

from veilio_sdk import VeilioClient

# Initialize client
client = VeilioClient(
    api_key="veil_dev_your-api-key-here",
    base_url="https://app.veilio.xyz/api"  # Optional, defaults to production
)

# Tokenize sensitive data
result = client.tokenize(
    data="john@example.com",
    type="email"
)

print(f"Token: {result['token']}")

# Detokenize when needed
original = client.detokenize(
    token=result["token"],
    reason="Send email notification"
)

print(f"Original: {original['data']}")

Features

• ✅ Simple tokenization - Tokenize single fields
• ✅ Bulk operations - Tokenize/detokenize multiple fields at once
• ✅ Multi-format support - JSON, CSV, SQL formats
• ✅ Crypto shredding - Immediate token shredding (shred_token)
• ✅ Retention policies - Automatic shredding via retention
• ✅ Automatic retries - Handles rate limits and network errors
• ✅ Error handling - Clear error messages and types
• ✅ Type hints - Full type annotations included

API Reference

Constructor

client = VeilioClient(
    api_key: str,              # Required: Your Veilio API key
    base_url: str = "https://app.veilio.xyz/api",  # Optional
    timeout: int = 30,         # Optional: Request timeout in seconds
    max_retries: int = 3       # Optional: Max retries for failed requests
)

Methods

tokenize(data, type=None, metadata=None, retention=None)

Tokenize a single field.

result = client.tokenize(
    data="john@example.com",
    type="email",              # Optional
    metadata={"source": "form"},  # Optional
    retention={                  # Optional
        "ttlDays": 30
        # or "retentionUntil": "2026-12-31T23:59:59.000Z"
    }
)

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

tokenize_bulk(fields)

Tokenize multiple fields in one request.

result = client.tokenize_bulk([
    {"data": "john@example.com", "type": "email"},
    {"data": "+33612345678", "type": "phone"}
])

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

detokenize(token, reason=None)

Detokenize a single token.

result = client.detokenize(
    token="tok_abc123...",
    reason="Send email"  # Optional
)

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

shred_token(token, reason=None)

Shred a token immediately (cryptographic erasure).

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

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

detokenize_bulk(tokens, reason=None)

Detokenize multiple tokens in one request.

result = client.detokenize_bulk(
    [
        {"token": "tok_abc123...", "reason": "Profile view"},
        {"token": "tok_def456...", "reason": "Profile view"},
    ],
    reason="Profile view",  # optional batch-level audit reason (one log line)
)

# Returns: {
#     "results": [...],
#     "summary": {"total": int, "success": int, "failed": int},
#     "errors": [...],  # Optional
#     "accessedAt": str
# }

tokenize_format(data, format=None, options=None)

Tokenize structured data (JSON, CSV, SQL).

json_data = '{"email": "john@example.com"}'

result = client.tokenize_format(
    data=json_data,
    format="json",  # Optional: auto-detected if omitted
    options={
        "fields": ["email"]  # Optional: tokenize only specific fields
    }
)

# Returns: {
#     "format": str,
#     "tokenizedData": str,
#     "tokens": [...],
#     "metadata": {...},
#     "summary": {"totalFields": int, "tokenizedFields": int}
# }

detokenize_format(tokenized_data, format, tokens)

Detokenize structured data.

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

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

Examples

Basic Usage

from veilio_sdk import VeilioClient
import os

client = VeilioClient(api_key=os.getenv("VEILIO_API_KEY"))

# Tokenize
token = client.tokenize(data="sensitive@data.com", type="email")

# Store token in your database
# db.execute("INSERT INTO users (email) VALUES (?)", (token["token"],))

# Later, detokenize when needed
user = db.get_user(user_id)
email = client.detokenize(token=user.email, reason="Send notification")

Bulk Operations

# Tokenize multiple fields at once
result = client.tokenize_bulk([
    {"data": "john@example.com", "type": "email"},
    {"data": "+33612345678", "type": "phone"},
    {"data": "123-45-6789", "type": "ssn"}
])

# Check for errors
if result["summary"]["failed"] > 0:
    print(f"Errors: {result.get('errors', [])}")

# Use the tokens
for token_result in result["tokens"]:
    print(f"Token: {token_result['token']}")

Format Tokenization

# Tokenize JSON data
json_data = json.dumps({
    "users": [
        {"email": "john@example.com", "phone": "+33612345678"}
    ]
})

result = client.tokenize_format(data=json_data, format="json")

# Store tokenized JSON
# db.save(result["tokenizedData"])

# Later, detokenize
recovered = client.detokenize_format(
    tokenized_data=result["tokenizedData"],
    format="json",
    tokens=[{"path": t["path"], "token": t["token"]} for t in result["tokens"]]
)

Error Handling

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

try:
    result = client.tokenize(data="test")
except AuthenticationError as e:
    print(f"Auth error: {e.message}")
except RateLimitError as e:
    print(f"Rate limit: {e.message}, retry after {e.retry_after}s")
except TokenShreddedError as e:
    print(f"Token shredded: {e.message}")
except VeilioError as e:
    print(f"API error: {e.code} - {e.message}")

Error Codes

• AUTH_ERROR - Invalid or missing API key
• VALIDATION_ERROR - Invalid request data
• RATE_LIMIT_ERROR - Rate limit exceeded
• PLAN_LIMIT - Plan limit exceeded
• TOKEN_SHREDDED - Token has been cryptographically shredded
• INTERNAL_ERROR - Server error

Requirements

• Python 3.8+
• requests library

License

MIT

Support

• Documentation: https://docs.veilio.xyz
• Support: support@veilio.xyz