Skip to content

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"
}

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