Workspace

O Workspace é a raiz multi-tenant do modelo de dados. Todos os outros recursos pertencem a exatamente um workspace. Workspaces espelham uma conta Kobana upstream; são provisionados por um hook interno, não por usuários finais.

:::info Escopo As rotas de workspace resolvem dentro da organização do workspace do token: GET /workspaces lista todo workspace vivo dessa organização, e GET, PATCH, DELETE /workspaces/{id} e PUT /workspaces alcançam qualquer um deles; um workspace de outra organização é um 404 simples. Um token cujo workspace não tem organização enxerga só a si mesmo. Criação, exclusão e alteração de limites continuam exigindo token src=system, e POST/PUT criam o workspace dentro da organização do token. Todos os outros recursos seguem escopados ao próprio workspace do token. :::

Propósito

• Isolamento de tenant: cada chamada de API resolve um workspace a partir do claim sub do JWT, e toda query é automaticamente filtrada por ele.
• Cotas de uso: o workspace carrega caps mensais de custo / e-mails usados pelo agent runner para throttle.
• Binding cross-product: source indica qual produto Kobana o workspace espelha (kobana_app, kobana_billing, etc.).

Schema

Campo	Tipo	Descrição
id	UUID	ID interno.
external_id	UUID	account_public_id do sistema de origem. Unique.
source	enum	kobana_app, kobana_billing, kobana_autonomous_inbox, kobana_agent, kobana_finance, kobana_legal, kobana_team.
label	string	Label humano.
monthly_cost_limit	decimal | null	Cap em USD para agent runs por mês calendário. null = sem limite.
monthly_cost_used	decimal	Custo acumulado no mês atual.
monthly_emails_limit	int | null	Cap de e-mails processados no mês.
monthly_emails_used	int	E-mails acumulados no mês atual.
custom_metadata	object	Free-form. Retornado as-is.
metadata	object	Controlado pelo sistema (rate-limit tier, feature flags).
created_at	datetime
updated_at	datetime
deleted_at	datetime | null	Marcador de soft-delete.

Exemplo

{
  "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
}

Ciclo de vida

• Provisionamento — kobana-app chama POST /v1/workspaces com JWT src=system quando uma nova conta é criada upstream.
• Updates — PATCH /workspaces/{id} para atualizar label, monthly_cost_limit, monthly_emails_limit, custom_metadata.
• Soft-delete — DELETE /workspaces/{id} define deleted_at. Inboxes/emails em cascade não são deletados; eles ficam inalcançáveis pela API porque requisições futuras resolvem para um workspace soft-deletado.

Contadores

monthly_cost_used e monthly_emails_used são resetados por um cron interno no primeiro segundo de cada mês (timezone do workspace ainda não é suportada — o reset é em UTC).