Admin Guide
Platform-wide configuration for Organization Administrators and Super Admins. Covers initial setup, workspace management, connection governance, environment configuration, and compliance audit trails.
Organization Setup
After your first login as Super Administrator, configure the platform-wide settings before adding users or creating workspaces.
System Roles
| Role | Scope | Key Capabilities |
|---|---|---|
| Super Administrator | Platform-wide | Full unrestricted access to all organizations, billing, infrastructure diagnostics, global audit logs. Can impersonate users (audit-logged). Cannot be deleted — only transferred. |
| Organization Admin | Within organization | Creates workspaces and workspace admins. Configures SSO, MFA, password policies, and IP allowlists. Manages org-level connections and licensed connectors. Views all org audit logs. |
| Workspace Admin | Within workspace | Creates and manages projects, folders, and pipelines. Assigns users to projects. Configures workspace-level settings (default environments, shared connections). Cannot modify org-level SSO or billing. |
Initial Organization Configuration Checklist
- Configure SSO (SAML 2.0 or OIDC) or set local password policy. → SSO guide
- Set MFA enforcement policy (required / optional / admin-only).
- Configure IP allowlist for admin access.
- Create shared connections (databases, cloud buckets) available to all workspaces.
- Invite the first Workspace Admins and assign them to their workspaces.
- Set audit log retention policy (default: 90 days; configurable up to 365 days).
Projects & Workspaces
The resource hierarchy is: Organization → Workspace → Project → Folder → Pipeline → Job/Run. Permissions cascade downward unless explicitly overridden at a lower level.
Creating a Workspace
- Navigate to Admin → Workspaces → New Workspace.
- Set name, description, and assign a Workspace Administrator.
- Configure default compute environment (Spark endpoint or Databricks workspace).
- Optionally bind shared organization connections.
Creating a Project
- Inside the workspace, go to Projects → New Project.
- Set name, description, and assign a Project Owner.
- Configure project-level connections and environment bindings.
- Add initial team members with appropriate roles (Developer, Analyst, Operator, Approver).
Connection Management
Connections are the credentials and configuration needed to reach a data source or target. They are centrally managed and referenced by pipelines.
Connection Scopes
- Organization-level connections — Shared across all workspaces. Managed by Org Admin.
- Workspace-level connections — Shared across all projects in the workspace. Managed by Workspace Admin.
- Project-level connections — Available only within the project. Managed by Project Owner or Connection Manager role.
Connectivity Methods
| Method | Use Case |
|---|---|
| Direct Connection | Standard cloud-to-cloud. Source and DataKnits are both reachable over the internet. |
| SSH Tunneling | Database behind a firewall. DataKnits connects to an SSH bastion host first. |
| On-Prem Agent | Outbound-only WebSocket connection from inside a private subnet. Agent initiates the tunnel — no inbound firewall rules required. See the Secure Agent guide. |
Credential Storage
All credentials are encrypted at rest with AES-256 (PostgreSQL pgcrypto extension). Connection managers can create and rotate credentials but can never view plaintext values — all credential fields are write-only via vault after initial entry.
Environments
Environments bind a Spark compute endpoint to an execution context (Development, Staging, Production). Each project can have multiple environments.
- Development — Developers can run pipelines freely. No approval required.
- Staging — Developers can run pipelines. Production-equivalent data; requires same configuration as prod.
- Production — Requires Approver sign-off before a pipeline is promoted. Only Executor/Operator roles can trigger runs.
Each environment stores its own set of runtime variables (e.g., S3 bucket names, database hostnames) which are injected into generated code at execution time — no code changes required to promote from staging to production.
Environment Variables (.env)
DataKnits follows the Twelve-Factor App pattern. Configuration values are read from .env files at startup — never hard-coded.
Backend Variables (Backend/.env)
| Variable | Required | Description |
|---|---|---|
PORT | optional | HTTP port for the API server. Default: 3000. |
DB_HOST | required | PostgreSQL host. |
DB_PORT | optional | PostgreSQL port. Default: 5432. |
DB_NAME | required | Database name (e.g. etl_db). |
DB_USER | required | PostgreSQL username. |
DB_PASSWORD | required | PostgreSQL password. |
JWT_SECRET | required | Secret key for signing JWTs. Must be at least 32 characters. Generate with openssl rand -hex 32. |
ENCRYPTION_KEY | required | AES-256 key for connector credential encryption. |
SERVE_FRONTEND | optional | Set to true to serve the built frontend from dist/public/. For production single-binary deploys. |
NODE_ENV | optional | development or production. Controls error verbosity and logging. |
Frontend Variables (Frontend/.env)
VITE_ are injected into the browser bundle. Never put backend secrets in a VITE_ variable.| Variable | Required | Description |
|---|---|---|
VITE_API_URL | required | Base URL of the DataKnits backend API (e.g. https://etl.dataknits.com/api). |
VITE_WS_URL | required | WebSocket URL for real-time execution monitoring. |
Audit Logging & Compliance
Every significant state change is recorded in the audit log with who, what, when, and from where. Audit triggers are implemented as PostgreSQL triggers — they cannot be bypassed by the application layer.
Audited Events
- User login / logout / failed login attempts.
- User creation, modification, and deactivation.
- Role assignment and revocation.
- Pipeline create, edit, version, publish, delete.
- Connection create, rotate credentials, delete.
- Pipeline execution start, completion, failure, cancellation.
- Admin impersonation sessions.
- Permission override events.
Compliance Standards
DataKnits is architected for compliance with the following standards. See the Security & Trust page for attestation details.
- SOC 2 Type II — audit controls, access management, availability.
- ISO 27001 — information security management.
- GDPR — data minimization; no customer data stored on DataKnits servers.
- HIPAA — supported via Business Associate Agreement (BAA) on enterprise plans.
- PCI-DSS — card data never transits DataKnits (execution-plane separation).