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 (PROVISIONING, ACTIVE, SUSPENDED, CLOSED)
  • 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)

Closure (the operation formerly described here as "deletion"):

  • The tenant record is retained, marked CLOSED, and the state is terminal — a closed tenant cannot be reopened, and its identifier is never reused.
  • The tenant's authority is withdrawn: its applications are revoked, its cryptographic actors disabled, its capability grants revoked, and the standing assertions it made — federated identity bindings, its own trusted issuers, verified e-mail domains, support-access consent — are disposed of. No credential of a closed tenant can authenticate, and no token already issued resolves a permission.
  • Keys and audit records are retained, not destroyed. Closure drives no key lifecycle transition: the keys are unusable the moment the tenant is CLOSED, and the retained audit trail references them, so destroying their custody record would make retained events unverifiable. Audit logs are retained under their own retention policy; nothing archives or deletes them as part of a closure.

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): 

// The token carries the tenant; every call is scoped to it automatically.
// Key provisioning itself is a control-plane operation (Admin Console,
// ankasecure-cli-admin, or the Admin API) -- the SDK does not create keys.
KeyMetadata key = client.getKeyMetadata("customer-data-key");
// Resolves only within YOUR tenant's keystore; a kid from another tenant is not visible

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