Workspace

The Workspace is the multi-tenant root of the data model. Every other resource hangs off exactly one workspace. Workspaces mirror an upstream Kobana account; they are provisioned through an internal hook, not by end users.

:::info Scope Workspace routes resolve within the organization of the token's workspace: GET /workspaces lists every live workspace of that organization, and GET, PATCH, DELETE /workspaces/{id} and PUT /workspaces reach any of them; a workspace of another organization is a plain 404. A token whose workspace has no organization only sees itself. Creation, deletion and limit changes still require a src=system token, and POST/PUT create the workspace inside the token's organization. Every other resource stays scoped to the token's own workspace. :::

Purpose

• Tenant isolation: every API call resolves a workspace from the JWT sub claim, and every query is automatically scoped to it.
• Usage quotas: the workspace carries monthly cost / email caps used by the agent runner to throttle execution.
• Cross-product binding: source indicates which Kobana product the workspace mirrors (kobana_app, kobana_billing, etc.).

Schema

Field	Type	Description
id	UUID	Internal id.
external_id	UUID	account_public_id from the source system. Unique.
source	enum	kobana_app, kobana_billing, kobana_autonomous_inbox, kobana_agent, kobana_finance, kobana_legal, kobana_team.
label	string	Human label.
monthly_cost_limit	decimal | null	USD cap for agent runs per calendar month. null = unlimited.
monthly_cost_used	decimal	Accumulated cost for the current month.
monthly_emails_limit	int | null	Cap on processed emails per month.
monthly_emails_used	int	Accumulated emails for the current month.
custom_metadata	object	Free-form. Returned as-is.
metadata	object	System-controlled (rate-limit tier, feature flags).
created_at	datetime
updated_at	datetime
deleted_at	datetime | null	Soft-delete marker.

Example

{
  "id": "a8b2c1d4-9e7f-4a3b-8c5d-1f2e3a4b5c6d",
  "external_id": "00000000-0000-0000-0000-000000abc123",
  "source": "kobana_app",
  "label": "Acme Cobrança",
  "monthly_cost_limit": "250.00000",
  "monthly_cost_used": "47.12834",
  "monthly_emails_limit": 50000,
  "monthly_emails_used": 8421,
  "custom_metadata": { "owner_email": "ops@acme.com" },
  "metadata": { "rate_limit_tier": "premium" },
  "created_at": "2026-01-04T12:00:00.000Z",
  "updated_at": "2026-05-17T09:14:22.481Z",
  "deleted_at": null
}

Lifecycle

• Provisioning — kobana-app calls POST /v1/workspaces with src=system JWT when a new account is created upstream.
• Updates — PATCH /workspaces/{id} to update label, monthly_cost_limit, monthly_emails_limit, custom_metadata.
• Soft-delete — DELETE /workspaces/{id} sets deleted_at. Cascading inboxes/emails are not deleted; they become unreachable through the API because future requests resolve to a soft-deleted workspace.

Counters

monthly_cost_used and monthly_emails_used are reset by an internal cron at the first second of each month (workspace-local timezone is not yet supported — reset is UTC).