Workspaces

Postato has a two-level hierarchy: tenant at the top, workspace underneath.

Tenant

The billing and organization boundary. One tenant = one company (or one solo account). A tenant owns:

• Users and their roles (owner, super_admin, member)
• Billing plan and payment method
• Agents and the API keys they issue
• Any number of workspaces

Workspace

A container for a brand, client, or initiative. Workspaces own the day-to-day content surface:

• Social accounts (OAuth connections to X, LinkedIn, Instagram, etc.)
• Posts and scheduled queue
• Media uploads
• Webhook subscriptions
• Approval policies

A workspace can be soft-deleted (by setting deletedAt) but never hard-deleted. Historical records remain intact for audit and compliance.

Access rules

Tenant roles

• owner / super_admin: implicit access to every live workspace in the tenant. They don't need explicit grants.
• member: needs an explicit grant in workspaceMembers with one of: admin, editor, approver, viewer.

Agent grants

An agent is a programmatic identity (an AI agent, a backend service, a CI worker). Agents have their own workspace grants in agentWorkspaceGrants, independent of the human who created them. This means when a team member leaves, their agents survive with the same grants; they don't lose access just because the creator lost tenant membership.

API key scope

Every API key carries a scope:

Use all when you want the key to automatically extend to new workspaces the agent gains access to; use selected when you want a fixed subset. A "single workspace" key is just selected with one entry.

Agent management scope

Agents themselves have a managementScope flag set at creation time, separate from API key scope. It decides who can edit, rotate, or revoke the agent:

Agents created from the workspace surface (/agents/new) are always workspace-managed. Agents created from the tenant surface (/org/agents/new) are always tenant-managed. To change the level, revoke and recreate. When a workspace is soft-deleted, every workspace-managed agent grant-bound to it is automatically orphaned.

Request resolution

Every request resolves a set of allowed workspace IDs for the caller, live (no caching):

1. REST routes live under /v1/workspaces/{workspaceId}/.... The ID in the path must be in the caller's allowed set.
2. MCP tools receive workspaceId as an argument. The tool wrapper validates it before calling the handler.
3. If a caller has access to exactly one workspace, some endpoints auto-resolve. Callers with multiple workspaces must pass the ID explicitly; omitting it returns 400 workspace_required with the list of options in the body.

Invariants

A few rules the platform enforces so you don't have to:

1. No silent defaults. Ambiguous workspace = 400, never a wrong guess.
2. Explicit grants. Gaining access to a new workspace does NOT expand a selected key. Only all keys extend dynamically.
3. Creator cap. You can only grant workspace access you yourself currently have.
4. Soft-delete opacity. A soft-deleted workspace is indistinguishable from "not found" to anyone who can't restore it.
5. Workspace-scoped data is never cross-leaked. Queries are always filtered by (tenantId, workspaceId) together.

Creating workspaces

From the dashboard: Settings → Workspaces → New. Via REST: POST /v1/workspaces. Naming is free-form; there is no uniqueness requirement across the tenant.

Migrating ownership of a resource

Workspaces are the unit of data ownership. Moving a post between workspaces is not supported; the social account it was published from belongs to a specific workspace. If you need to consolidate content from many sources, publish to the destination workspace directly from the start.