Workspace

El Workspace es la raíz multi-tenant del modelo de datos. Todos los demás recursos pertenecen a exactamente un workspace. Los workspaces reflejan una cuenta Kobana upstream; se aprovisionan mediante un hook interno, no por usuarios finales.

:::info Alcance Las rutas de workspace se resuelven dentro de la organización del workspace del token: GET /workspaces lista todo workspace vivo de esa organización, y GET, PATCH, DELETE /workspaces/{id} y PUT /workspaces alcanzan cualquiera de ellos; un workspace de otra organización es un 404 simple. Un token cuyo workspace no tiene organización solo se ve a sí mismo. La creación, la eliminación y el cambio de límites siguen requiriendo un token src=system, y POST/PUT crean el workspace dentro de la organización del token. Todos los demás recursos siguen acotados al propio workspace del token. :::

Propósito

• Aislamiento de tenant: cada llamada a la API resuelve un workspace a partir del claim sub del JWT, y cada query se filtra automáticamente por él.
• Cuotas de uso: el workspace lleva topes mensuales de costo/correos usados por el agent runner para aplicar throttling.
• Vinculación cross-product: source indica qué producto Kobana refleja el workspace (kobana_app, kobana_billing, etc.).

Schema

Campo	Tipo	Descripción
id	UUID	ID interno.
external_id	UUID	account_public_id del sistema de origen. Único.
source	enum	kobana_app, kobana_billing, kobana_autonomous_inbox, kobana_agent, kobana_finance, kobana_legal, kobana_team.
label	string	Etiqueta legible.
monthly_cost_limit	decimal | null	Tope en USD para agent runs por mes calendario. null = sin límite.
monthly_cost_used	decimal	Costo acumulado del mes actual.
monthly_emails_limit	int | null	Tope de correos procesados por mes.
monthly_emails_used	int	Correos acumulados del mes actual.
custom_metadata	object	Formato libre. Devuelto tal cual.
metadata	object	Controlado por el sistema (tier de rate-limit, feature flags).
created_at	datetime
updated_at	datetime
deleted_at	datetime | null	Marcador de soft-delete.

Ejemplo

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

• Aprovisionamiento — kobana-app llama a POST /v1/workspaces con un JWT src=system cuando se crea una nueva cuenta upstream.
• Actualizaciones — PATCH /workspaces/{id} para actualizar label, monthly_cost_limit, monthly_emails_limit, custom_metadata.
• Soft-delete — DELETE /workspaces/{id} establece deleted_at. Los inboxes/correos en cascada no se eliminan; quedan inalcanzables a través de la API porque las solicitudes futuras resuelven a un workspace soft-deleted.

Contadores

monthly_cost_used y monthly_emails_used se reinician mediante un cron interno en el primer segundo de cada mes (la zona horaria local del workspace aún no está soportada — el reinicio es en UTC).