Platform Overview

Services

Ergon is composed of purpose-built services that each own a distinct domain. Every service exposes its own REST API and communicates with other services through an event-based messaging system. All services share a central IAM layer for authentication and use cross-service grants to access each other's resources in a controlled way.

Architecture

Each service runs independently behind an API gateway that routes requests by path prefix. Services communicate asynchronously through an event bus — every meaningful action emits a typed event that other services can consume. Background workers handle tasks like email delivery, document processing, formula computation, workflow automation execution, and agent inference.

Storage is per-service: each service owns its own database. S3-compatible object storage is shared for file uploads. The gateway provides a unified entry point so all services are reachable through a single base URL.

Each service is accessed through a shared base URL at https://platform.ergondata.ai with service-specific path prefixes. See the Getting Started guide for the full prefix table.

Multi-Tenancy

The platform uses a company as its unit of tenancy. Every resource — agents, workflows, documents, worksheets, channel addresses — belongs to exactly one company and is fully isolated from other companies.

When you create a company through IAM, you choose which services to enable. A company might use only Agent Hub and Buckets, or it might enable all services. Services can be enabled or disabled at any time without affecting other companies.

Within a company, all principals are scoped to that tenant:

• Members — human users invited to the company, each with a role that controls what they can access.
• Agents — AI agents configured within the company. An agent can only access resources belonging to its own company.
• API keys — credentials scoped to the company. A key created in one company cannot access another company's data.

Federated Zones

Ergon uses zero-trust federated zones for resource access. A federated zone is simply a resource whose access is granted on the concrete instance and managed from its own security page — never on its parent or its type as a whole. IAM controls who may create such a resource inside a company — a workflow folder, workflow, bucket, agent, skill, LLM config, automation project, or conversation project — and creating it opens a delegated zone scoped to that instance. The resource needn't contain sub-resources to be a zone; a skill or LLM config has none and is still its own zone.

The creator receives the first local permission bundle for that zone, including the service-specific manage permission needed to invite others. From then on, collaborators are delegated from the owning service's security page. Broad organization roles do not automatically grant access to everything inside the zone.

Authentication

All API calls are authenticated using short-lived access tokens issued by the IAM service. The flow is straightforward:

1. Create an API key (a client_id / client_secret pair) in the IAM console.
2. Exchange the credentials for an access token via the token endpoint.
3. Pass the token as a Bearer token in the Authorization header of every request.

Tokens expire after a set duration. When a token expires, request a new one using the same API key credentials.

Cross-Service Grants

Services on Ergon often need to access resources owned by other services. For example, a Workflow might need to read documents from a Buckets folder, or send messages through a Channel address. This is handled through grants — a controlled, two-sided permission model.

The Owner / Consumer Model

Every grant involves two parties:

• Owner — the service that owns the resource (e.g., Buckets owns a folder, Channels owns an address).
• Consumer — the service that wants to use the resource (e.g., Workflows wants to read from that folder).

Double Handshake

Granting access requires action from both sides — a deliberate design that prevents unintended access:

1. Owner grants access — the resource owner creates a grant specifying which consumer service and company may access the resource, and at what level (e.g., read-only or read-write).
2. Consumer selects the resource — the consuming service explicitly selects the granted resource for use in its own configuration (e.g., a Workflow picks a granted folder as its document source).

Neither side alone is sufficient. The owner must offer access, and the consumer must accept and bind it. Access is enforced at runtime — if a grant is revoked, the consumer immediately loses access.

Common Grant Scenarios

Events & Real-Time

The platform emits events whenever something meaningful happens — a document is uploaded, a workflow item moves to a new phase, an agent finishes a conversation turn. These events enable real-time UIs and asynchronous integrations.

Event Naming Convention

Events follow a consistent naming pattern:

{service}.{entity}.{action}

For example: buckets.files.ingested, workflows.items.routed, conversations.message.added. This convention makes it easy to filter and route events by service or entity type.

WebSocket Connections

For real-time updates, connect to a service's WebSocket endpoint. Each connection is scoped to a specific resource (a conversation, a workflow, a folder, or a worksheet) and streams events as they occur. This powers live UIs — streaming agent responses, showing file processing progress, or reflecting worksheet edits in real time.

WebSocket connections are authenticated using your access token passed as a query parameter. See the WebSocket reference for connection URLs and examples.

Webhooks

For server-to-server integrations, you can register webhook endpoints to receive event notifications via HTTP POST callbacks. Webhooks use the same event naming convention and include the full event payload in the request body.