Enterprise Features

Enterprise features provide advanced capabilities for organizations requiring programmatic access, event-driven integrations, and granular access control.

Enterprise Features

Enterprise-facing capabilities currently center on:

API keys for scoped programmatic access
webhooks for outbound event delivery
SCIM provisioning for managed identity lifecycle flows
social OAuth and organization SSO configuration
app access control across web, desktop, and mobile surfaces

Operator expectations are split cleanly:

org-specific credentials are configured in organization settings
system secrets remain environment-backed
every enterprise feature remains organization-scoped even when managed centrally by platform operators

For SCIM specifically, keep expectations narrower: the current product supports SCIM in the enterprise auth stack, but it does not currently expose a dedicated self-serve SCIM setup page in normal admin settings.

API Key Management

API keys enable secure programmatic access to Z8 APIs for integrations, automation, and third-party applications.

Permission Scopes

Scope	Description
`time-entries:read`	Read time entries
`time-entries:write`	Create and update time entries
`employees:read`	Read employee data
`reports:read`	Access analytics reports
`projects:read`	Read project information
`projects:write`	Manage projects

API Key Security

The full API key is shown only once at creation. Store it in a proper secret manager and rotate unused keys regularly.

Webhook System

Webhooks deliver organization-scoped events to external systems.

Architecture

webhook-service.ts

webhook-queue.ts

webhook-worker.ts

webhook-delivery.ts

webhook-subscriber.ts

signature.ts

types.ts

Delivery Model

events are emitted with organization context
matching webhook endpoints are resolved for that organization
deliveries are queued and retried through worker infrastructure
payloads are signed with HMAC-SHA256

SCIM Provisioning

SCIM support is part of the enterprise auth stack for managed provisioning. It should be understood as an organization-scoped integration, not a cross-tenant identity plane.

In practice this means:

one SCIM configuration provisions one organization at a time
provisioning activity can map members, role templates, and lifecycle events into that organization
SCIM rollout is usually coordinated by operators for enterprise customers rather than treated as a casual self-serve toggle in the product UI

Enterprise organizations can configure their own OAuth providers for branded sign-in and org-aware sign-up flows.

Supported Providers

Provider	Notes
Google	OAuth 2.0 with org-specific credentials
Microsoft	Azure AD / Microsoft identity flows
GitHub	OAuth Apps
LinkedIn	OAuth 2.0
Apple	Sign in with Apple with additional org config

Security Features

PKCE for code-exchange protection
state signing and nonce validation
secure cookie-backed web sessions
organization-aware callback routing

App Access Control

User-level app access flags control whether a member can use the web app, desktop app, or mobile app after authentication succeeds.

This is useful for mixed environments such as:

web-only contractor access
mobile-only field staff access
temporary desktop restrictions during rollout phases

interface AppPermissions {
  canUseWebapp: boolean;   // Web application access
  canUseDesktop: boolean;  // Desktop app access
  canUseMobile: boolean;   // Mobile app access
}

App Type Detection

The system automatically detects app type from request headers:

Auth Method	Signal	App Type
Cookie	Any	Webapp
Bearer token	`X-Z8-App-Type: mobile`	Mobile
Bearer token	`X-Z8-App-Type: desktop`	Desktop
Bearer token	No explicit app header	Legacy fallback based on user agent

Mobile-only API routes use the stricter contract: bearer token plus X-Z8-App-Type: mobile.

Access Validation

import { AppAccessService } from '@/lib/effect/services/app-access.service';

// Check access (returns result)
const result = await AppAccessService.checkAccess(userId, headers);
// { allowed: true, appType: 'webapp', permissions: {...} }

// Validate access (throws if denied)
const appType = await AppAccessService.validateAccess(userId, headers);

Audit Logging

All access changes and denials are logged:

Access granted/revoked: Who, when, which app
Access denied: User, app type, IP address, user agent

Use Cases

Restrict contractors to web-only access
Allow field workers mobile-only access
Limit desktop app to specific roles
Temporary access restrictions

Configuration

# API keys
API_KEY_ENCRYPTION_KEY=<32-byte-hex-key>

# Default social OAuth providers
GOOGLE_CLIENT_ID=<default-client-id>
GOOGLE_CLIENT_SECRET=<default-secret>

Organization-specific OAuth credentials, webhook endpoints, and enterprise integration settings should be entered in the product's org settings rather than duplicated as tenant-specific environment variables. Webhook retry and delivery behavior are handled by the application's worker and queue infrastructure, not by separate documented webhook-specific env knobs on this page.

Enterprise Features

On this page