Multi-Tenancy & Isolation

AnkaSecure provides secure multi-tenant architecture with strict data, resource, and security isolation. This document explains how the platform ensures tenant separation and protects your cryptographic keys and data from unauthorized access.

---

Multi-Tenancy Model

What is a Tenant?

A tenant represents an independent organization using AnkaSecure. Each tenant has:

• ✅ Isolated keystore: Cryptographic keys segregated per tenant
• ✅ Independent users: User accounts scoped to tenant
• ✅ Separate applications: API keys and OAuth clients per tenant
• ✅ Dedicated quotas: Rate limits and resource allocations

Example: If your company (ACME Corp) uses AnkaSecure, you are a tenant. Your cryptographic keys, users, and API calls are completely isolated from other tenants (Widgets Inc, Contoso, etc.).

---

Isolation Guarantees

An AnkaSecure provides three layers of isolation:

1. Data Isolation

Keystore Separation: - Each tenant has a dedicated keystore (logical or physical) - Keys from one tenant cannot be accessed by another tenant - Key IDs are tenant-scoped (Tenant A's "my-key" ≠ Tenant B's "my-key")

Cryptographic Operations: - Encryption/decryption operations validate tenant ownership - JWT claims include tenant ID validation - Cross-tenant operations are automatically rejected

Audit Logs: - Each tenant has isolated audit logs - Tenant A cannot view Tenant B's audit trail - Logs include tenant ID for compliance reporting

Verification Example:

# Attempt to access another tenant's key (should fail)
curl -X POST https://api.ankasecure.com/api/v1/crypto/encrypt \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-ID: tenant-a" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "tenant-b-key",  # ← Key from different tenant
    "plaintext": "..."
  }'

# Response: 403 Forbidden
# {
#   "error": "AUTH_003",
#   "message": "Access denied: key belongs to different tenant"
# }

---

2. Resource Isolation

Rate Limiting: - Per-tenant rate limits (not shared across tenants) - Tenant A's high traffic does not affect Tenant B's quota - Fair resource allocation via multi-tenant queuing

Quotas: - Per-tenant API call limits (operations/day, operations/month) - Per-tenant key generation limits (keys/day) - Per-tenant storage limits (keystore size)

Example Rate Limits (default, configurable):

- API Calls: 1,000,000 per month
- Key Generation: 10,000 keys per month
- Storage: 10 GB keystore per tenant

Verification (via response headers):

X-RateLimit-Limit: 60          # Requests per minute for THIS tenant
X-RateLimit-Remaining: 42      # Remaining quota for THIS tenant
X-RateLimit-Reset: 1735000000  # When THIS tenant's quota resets

---

3. Security Isolation

Authentication: - JWT tokens are tenant-specific (cannot be reused across tenants) - API keys are tenant-scoped - User accounts belong to single tenant (no cross-tenant users)

Authorization: - Role-Based Access Control (RBAC) per tenant - Tenant admins manage only their tenant (cannot access other tenants) - Platform admins (AnkaTech) have elevated cross-tenant visibility (for support)

Cryptographic Isolation: - Keys generated for Tenant A cannot encrypt/decrypt Tenant B's data - Key rotation for Tenant A does not affect Tenant B - HSM partitions (if used) are tenant-specific

---

Tenant Lifecycle

1. Tenant Provisioning

SaaS Model: - Tenant provisioned automatically during registration - Initial admin user created - Default keystore initialized

On-Premise Model: - Tenant provisioned by platform admin (AnkaTech services) - Custom configuration (HSM, identity provider, policies)

Tenant Metadata: - Tenant ID (unique identifier, e.g., acme-corp) - Tenant name (display name, e.g., "ACME Corporation") - Status (active, suspended, deleted) - Creation date

---

2. User Management

Per-Tenant Users: - Users belong to a single tenant - Username uniqueness enforced per tenant (alice@tenant-a ≠ alice@tenant-b) - Roles and permissions scoped to tenant

User Roles (per tenant): - Tenant Admin: Manage tenant configuration, users, applications - Application Admin: Generate API keys, manage applications - User: Perform cryptographic operations (encrypt, sign) - Auditor: Read-only access to audit logs

Role Assignment:

# Assign role to user (via Admin API or CLI)
curl -X PATCH https://api.ankasecure.com/api/admin/users/{userId} \
  -H "Authorization: Bearer TENANT_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "APPLICATION_ADMIN"}'

---

3. Application Management

Applications: Programmatic identities for service-to-service authentication

Per-Tenant Applications: - Each tenant can create multiple applications - Each application gets a unique API key - API keys are tenant-scoped (cannot access other tenants)

Application Creation:

# Create application and generate API key
curl -X POST https://api.ankasecure.com/api/admin/applications \
  -H "Authorization: Bearer TENANT_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "description": "Primary production service"
  }'

# Response:
# {
#   "applicationId": "app-123",
#   "apiKey": "ask_1234567890abcdef...",  # ← Tenant-scoped API key
#   "tenantId": "acme-corp"
# }

---

4. Tenant Suspension & Deletion

Suspension: - Temporarily disable tenant access (non-payment, security incident) - All API calls return 403 Forbidden - Data and keys preserved (can be re-enabled)

Deletion: - Permanent tenant removal - All keys deleted (cannot be recovered) - Audit logs archived (compliance retention) - Tenant ID retired (cannot be reused)

---

Security Considerations

JWT Validation & Tenant Enforcement

Every API request validates: 1. JWT signature (token authenticity) 2. JWT claims (issuer, audience, expiration, not-before) 3. Tenant ID match: X-Tenant-ID header must match JWT tenantId claim

Example JWT Claims:

{
  "iss": "https://auth.ankasecure.com",
  "aud": "api.ankasecure.com",
  "sub": "[email protected]",
  "tenantId": "acme-corp",  # ← Tenant isolation enforced here
  "exp": 1735000000,
  "nbf": 1734996400
}

Security Enforcement:

# Valid request (tenant ID matches JWT)
curl https://api.ankasecure.com/api/v1/crypto/encrypt \
  -H "Authorization: Bearer JWT_WITH_TENANT_A" \
  -H "X-Tenant-ID: tenant-a"  # ✅ Matches JWT claim

# Invalid request (tenant ID mismatch)
curl https://api.ankasecure.com/api/v1/crypto/encrypt \
  -H "Authorization: Bearer JWT_WITH_TENANT_A" \
  -H "X-Tenant-ID: tenant-b"  # ❌ Mismatch rejected

# Response: 403 Forbidden
# {
#   "error": "AUTH_003",
#   "message": "Tenant ID mismatch: JWT tenant (tenant-a) != header (tenant-b)"
# }

---

Keystore Isolation

Key Lookup Process: 1. Extract tenant ID from JWT claims 2. Retrieve keystore for that specific tenant 3. Look up requested key in tenant keystore 4. Verify key belongs to tenant (double-check) 5. Perform cryptographic operation

Cross-Tenant Protection: - Even if Tenant B knows Tenant A's key ID, access is denied - Key IDs are not globally unique (scoped to tenant) - HSM partitions (if used) are tenant-specific

Example (key generation with automatic tenant scoping):

// SDK automatically includes tenant ID from config
KeyGenerationRequest request = KeyGenerationRequest.builder()
    .algorithm("ML-KEM-768")
    .keyId("customer-data-key")  // ← Scoped to YOUR tenant
    .build();

KeyResponse key = client.generateKey(request);
// Key stored in YOUR tenant's keystore only

---

Multi-Tenant Best Practices

For Tenant Administrators

✅ DO: - Use unique tenant IDs (avoid generic names like "test", "demo") - Implement role-based access control (RBAC) within your tenant - Rotate API keys regularly (every 90 days) - Monitor audit logs for unauthorized access attempts - Set up alerts for suspicious activity (failed authentications, unusual encryption volumes)

❌ DON'T: - Share API keys across tenants (each tenant should have separate keys) - Use production keys in development environments - Store tenant credentials in public repositories - Assume other tenants' data is inaccessible (verify isolation regularly)

---

For Application Developers

✅ DO: - Always include X-Tenant-ID header in API requests - Validate tenant ID matches your expected tenant - Use separate API keys for dev, staging, production (different tenants recommended) - Implement retry logic with exponential backoff (respect rate limits)

❌ DON'T: - Hardcode tenant IDs in source code (use environment variables) - Skip tenant ID validation in responses - Retry indefinitely on 403 errors (likely authorization issue)

---

Compliance & Audit

Tenant Isolation for Compliance

HIPAA (Healthcare): - Each covered entity should be a separate tenant - PHI encryption keys isolated per tenant (prevent data mixing) - Audit logs segregated for BAA compliance

PCI-DSS (Finance): - Each merchant should be a separate tenant - Cardholder data encryption keys isolated per tenant - Log retention per tenant (12 months minimum)

GDPR (EU Privacy): - Each data controller should be a separate tenant - Personal data encrypted with tenant-specific keys - Data subject rights enforced per tenant

---

Audit Trail Verification

Verify Tenant Isolation (via audit logs):

# Request audit logs for your tenant
curl https://api.ankasecure.com/api/audit/logs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

# Response: Only YOUR tenant's operations (no cross-tenant data)

Audit Log Fields:

{
  "timestamp": "2025-12-26T10:15:30Z",
  "correlationId": "a1b2c3d4-e5f6-7890",
  "tenantId": "your-tenant-id",  # ← Verify this matches your tenant
  "userId": "[email protected]",
  "operation": "ENCRYPT",
  "keyId": "your-key-123",
  "status": "SUCCESS"
}

---

Related Documentation

• Platform Overview - Complete platform architecture
• Security & Compliance - Security model
• API Reference - Tenant-scoped API operations
• Getting Started - Quick start with tenant setup

---

Documentation Version: 3.0.0 Last Updated: 2025-12-26