Architecture and access control
How Scheduler Zero connects clients, shared contracts, product services and local authorization.
# Architecture and access control
Scheduler Zero uses one shared contract for its web, admin and mobile clients, REST API, and MCP capabilities. Authentication identifies the caller; Scheduler Zero's authorization layer decides what that caller may do in the requested Organization or Workspace.
## The request path
```text
Web / admin / mobile ── typed API client ──┐
REST integrations ───── personal key ─────┼── Effect API
MCP clients ── Cloudflare MCP Worker ─────┘ │
├── Credential verification
├── Local authorization + tenant resolution
├── Product services + Postgres
└── Durable jobs + provider integrations
```
The API runs the shared Effect HTTP contract and production adapters. Product services implement the behavior, Postgres holds product state and local authorization, and the jobs worker performs durable background work. External provider callbacks enter through the ingress service. The MCP Worker translates capability calls into API requests and forwards a live credential and verified grant context.
## Declare once, publish several interfaces
The contract declares request and response schemas, accepted principal kinds, permissions, agent scopes, confirmation and idempotency rules. OpenAPI documents REST operations. The capability registry declares goal-oriented MCP tools, which may invoke several underlying operations.
The docs build derives the [REST reference](/rest-api/reference), [MCP reference](/mcp/tools), and [authentication guide](/authentication) from those generated artifacts. A tool's inputs are its capability schema, not an inferred copy of a REST request. Its structured output can wrap non-object native results in `data`.
## Organization and Workspace
An **Organization** is the commercial parent: ownership, billing, members and role definitions live there. A **Workspace** is a child data tenant containing campaigns, leads, inboxes, tasks and other product records.
Requests identify their target explicitly through a route or MCP `workspaceId`. Authorization resolves the target's parent and the caller's current access. A verified identity, default preference or visible tool catalog does not grant access to another tenant.
## Authentication
WorkOS AuthKit verifies human credentials, sessions and MFA. A verified human subject contains identity and authentication facts, without Organization or role authority. Scheduler Zero creates and verifies personal API keys locally. Delegated agents and interactive MCP clients also carry registration or durable consent constraints.
Use a personal key for headless integrations or interactive OAuth for supported MCP clients. See [Connect a client](/mcp/connect) and the generated [authentication and authorization guide](/authentication).
## Authorization
Scheduler Zero owns memberships, roles, permission grants, invitations, key restrictions and agent consent in Postgres. The API combines current role assignments and checks the canonical permission required by the operation.
For a personal key, effective authority is the **owner's live permissions intersected with the key's restrictions**. Agent and OAuth authority is also bounded by the actor's permissions, registration, scopes, approved Workspaces and consent. A principal kind must be admitted by the endpoint; a broad scope does not override human-only policies or tenant isolation.
Read the current default roles, permission classes and endpoint access matrix in [auth.md](/auth.md). That document is regenerated from the RBAC definitions and endpoint contracts; it publishes no customer role assignments or secrets.
## Agent-readable documentation
- [llms.txt](/llms.txt): every guide and tool permalink.
- [llms-full.txt](/llms-full.txt): complete guides, REST operations and exact MCP schemas.
- [auth.md](/auth.md): generated credential, RBAC and endpoint-policy reference.
- [OpenAPI](/openapi.json): public REST contract.
- [MCP catalog](/mcp-catalog.json): tool metadata and schemas for both credential variants.
Scheduler Zero