Skip to main content

​
Authentication & Authorization

The Zild Platform is designed with enterprise-grade authentication and authorization controls. This document explains how access is secured across:
  • API access
  • Webhook endpoints
  • User access
  • Tenant isolation
  • Role-based permissions
Authentication ensures identity verification.
Authorization ensures controlled access within tenant boundaries.

​
Authentication Model Overview

Zild uses a layered authentication model:
  1. API authentication (machine-to-machine)
  2. Webhook signature verification
  3. User authentication (admin panel access)
  4. Tenant-scoped authorization
  5. Role-based access control (RBAC)
Each layer protects a different surface of the system.

​
API Authentication

External systems communicate with Zild via secure APIs.

​
API Keys

Each Tenant is issued secure API credentials. Characteristics:
  • Tenant-scoped
  • Required in request headers
  • Rotatable
  • Revocable
  • Auditable

​
Example Header

Authorization: Bearer YOUR_API_KEY Requests without valid credentials are rejected.

​
API Key Best Practices

For production environments:
  • Store keys securely (e.g., environment variables or secret manager)
  • Never expose keys in frontend code
  • Rotate keys periodically
  • Restrict access to authorized systems only

​
Webhook Security

Zild both receives and sends webhooks. Security mechanisms ensure authenticity and integrity.

​
Inbound Webhooks (Channel Providers → Zild)

When receiving webhooks from providers (e.g., WhatsApp or Voice):
  • Signature validation is enforced (when supported by the provider)
  • Endpoint authentication is validated
  • Payload structure is verified
  • Tenant resolution is performed before processing
Requests that fail validation are rejected before reaching the orchestration layer.

​
Outbound Webhooks (Zild → External Systems)

When Zild triggers webhooks:
  • Configured per Tenant
  • HTTPS endpoints required
  • Signed payloads (when enabled)
  • Retry logic for transient failures
Recommended external validation:
  • Validate request signature
  • Restrict IP ranges (if applicable)
  • Use idempotency handling

​
User Authentication (Admin Access)

Access to the Zild Admin Panel requires authenticated user credentials. Supported mechanisms may include:
  • Email + password
  • Single Sign-On (SSO)
  • Enterprise identity provider integration (when configured)
User sessions are:
  • Time-bound
  • Revocable
  • Tenant-scoped

​
Role-Based Access Control (RBAC)

Authorization is enforced using role-based permissions. Users are assigned roles within a Tenant. Typical permission scopes include:
  • View conversations
  • Manage agents
  • Configure apps
  • Manage workflows
  • Access analytics
  • Manage integrations
  • Admin-level configuration
Permissions are evaluated on every protected action.

​
Tenant-Scoped Authorization

All access is tenant-scoped. When a request is authenticated:
  1. The Tenant is identified
  2. Access is validated against that Tenant
  3. Data queries are restricted to that Tenant boundary
No cross-tenant access is allowed. This is enforced at:
  • API layer
  • Data access layer
  • Workflow execution layer
  • Conversation retrieval layer

​
Internal Service Authentication

Within the platform architecture:
  • Services authenticate using internal secure channels
  • Service-to-service communication is protected
  • Access is restricted to required components only
This prevents unauthorized internal access or privilege escalation.

​
Principle of Least Privilege

Zild follows the principle of least privilege:
  • Users receive only required permissions
  • API keys are tenant-scoped
  • Workflows cannot access other tenant resources
  • Integrations are isolated per tenant
This minimizes attack surface and reduces operational risk.

​
Key Rotation & Revocation

API credentials can be:
  • Rotated
  • Revoked
  • Reissued
Revoked keys immediately lose access privileges. Key management events are logged for auditing.

​
Audit Logging

Security-sensitive actions are logged, including:
  • API authentication attempts
  • Failed authentication attempts
  • Role changes
  • Configuration changes
  • Workflow modifications
  • Integration updates
This supports:
  • Compliance auditing
  • Security investigations
  • Operational traceability

​
Recommended Security Practices for Integrators

When integrating with Zild:
  • Use HTTPS for all communication
  • Validate webhook signatures
  • Implement idempotency in webhook receivers
  • Protect API credentials using secret management
  • Apply least-privilege access internally
  • Monitor authentication logs

​
Summary

Zild secures access through multiple layers:
  • API authentication
  • Webhook validation
  • Tenant-scoped authorization
  • Role-based access control
  • Audit logging
These mechanisms ensure:
  • Strict tenant isolation
  • Secure integration management
  • Controlled user access
  • Enterprise-grade security posture
Authentication verifies identity.
Authorization enforces boundaries. Together, they maintain the integrity and isolation of the Zild Platform.