Spaces

An AI Space is KeenAgents' organizational unit for deploying agents: "Spaces are organizational units that group agents and control consumer access." Every agent belongs to exactly one space, and consumer-facing access is granted space-by-space — a partner's consumer contract lists which spaces its consumers may reach, and a consumer's login token carries the space entitlements derived from that contract. When an end user runs an agent, KeenAgents checks both that the token grants the requested space and that the target agent actually lives in that space.

A space itself is small: a stable ID, a title, a description, a deployment token, timestamps, and its list of agents. Creating a space also provisions the storage where its deployed flow-project files live; deleting the space removes those files again. The space's ID doubles as the project ID that clients and keen-builder (the deploy tool) reference.

Deployment token

A credential generated for you when the space is created — keen-builder authenticates deploys into the space with it. It is never chosen by the user, is read-only in the UI (with a Copy button), and can be re-minted with Reset Token. Re-minting invalidates the previous token immediately: any pipeline still holding the old value stops being able to deploy.

Space ID = project ID

The space's ID is "the stable identifier clients and keen-builder reference this space by." It is generated for you, never changes, and is what end-user chat clients pass as the project identifier. The detail page exposes it with a copy button for local project setup.

Agents in a space

Every agent is permanently linked to its space. Deleting a space deletes all of its agents with it, and each agent's settings and partner-facing front settings go with them — one delete removes the whole unit, so nothing orphaned is left behind.

Consumer entitlement

A partner's consumer contract (managed in the API Keys area) carries a master list of assigned spaces plus default space lists for newly registered consumers; a consumer's issued token is clamped to the contract's spaces. At run time KeenAgents enforces two-stage authorization: the token must grant the requested space, and the requested agent must exist (and be active) inside it. Removing a space from a contract removes it from affected consumers automatically.

Platform synchronization

Every space or agent change takes effect across the whole product automatically — other admin views and the partner surface converge within a few seconds, with no action needed on your part. Space views show only whether an agent has settings; the settings values themselves live on each agent's dedicated settings pages, which keeps space listings fast even with very large settings.

• Title — required, trimmed, maximum 150 characters, and unique across the platform: two spaces cannot share a title.
• Description — required on create, maximum 500 characters, and also unique: two spaces cannot share a description.
• Deployment token — generated by the platform at create; users never set it. Reset mints a fresh token and invalidates the old one immediately, so a leaked or retired credential can be cut off on the spot.
• Space ID — generated by the platform, immutable, doubling as the project ID referenced by clients and keen-builder.
• Organization-wide cap — 20 spaces, checked on create only; past the cap the create fails with a limit reached message. Delete a space first to make room.
• Delete cascade — deleting a space deletes all of its agents, each agent's settings and front settings, and the space's deployed project files. One action removes the whole unit so no stale agents or files linger.
• Error responses are deliberately general — any failed create/update/delete returns a "Not Acceptable" refusal without disclosing which rule failed; a duplicate title and a duplicate description are not distinguished to the caller. This keeps refusals from leaking information about existing records.
• Validation runs at every layer — the form checks the rules before submitting, they are checked again before the request leaves your browser, and KeenAgents itself remains the final authority, so an out-of-date or bypassed form can never write an invalid space.
• Every mutation is recorded in the audit trail — with the requester's email, user ID, and role, so every change is attributable.

1. Admin opens Spaces → Create Space and enters Title (≤150 chars) and Description (≤500 chars); both are required.
2. The form validates the rules on submit, and they are checked once more before the request leaves your browser.
3. KeenAgents validates the request, mints the deployment token for you, and creates the space; a duplicate title or description is refused with a general "Not Acceptable" error.
4. The action is recorded in the audit trail with the requester identity, and the space's deployed-project storage is provisioned.
5. The rest of the platform picks up the new space within seconds, and partner webhooks receive the r_space signal.
6. The UI shows a success toast and redirects straight to the new space's detail page.

Partner synchronization is notify-then-fetch: the webhook body carries only a signal, never data — the partner re-fetches current state through its authenticated partner API access, so stale or intercepted webhook payloads can never carry real content. Agent mutations fire their own r_agent kind because an agent edit does not change the space itself.

POST <your webhook URL>

{"synch-data": ["r_space"]}                      a space was created, updated, or deleted
{"synch-data": ["r_agent"]}                      an agent inside a space changed
{"synch-data": ["r_agent_front_settings"]}       an agent's partner-facing front settings were saved

• /spaces/list — table of all spaces with columns Title, ID, Agents Count, and a Visit link to each space's detail page.
• /spaces/create — Title and Description fields with live max-length enforcement (150 / 500), helper texts noting uniqueness, inline field errors, and a server-error line for refusals. Success redirects to the new space's detail page.
• /spaces/[id] — edit form for Title and Description with a dirty-gated Save: it activates only when a value actually deviates from the loaded record, and re-disables after a successful save.
• Detail page — read-only Deployment Token field with Copy and Reset Token buttons, and a read-only Space ID field with a Copy button.
• Detail page — two-step Delete: the button is replaced by a Confirm delete / Cancel pair (no browser popup); deleting navigates back to the list.
• Detail page — Assigned Agents table (Display Name, ID, Active, Start Flow, Start Node) with a Visit link to each agent's own page; hidden when the space has no agents.
• The agents section lists per-space (a space picker drives it) and pre-selects the space when navigated from a space context.
• Detail page — a Rebuild Resource Cache button rebuilds this space's served configuration on demand, a shortcut to the same action on the Cache page. It is gated by the cache permission (cache read, cache:w write), separate from the edit permission, so a cache manager can refresh it while an editor without cache rights never sees the button. You rarely need it — normal saves refresh the copy automatically. See Resource Cache.

A space's detail screen — title and description, the deployment token and Space ID with copy, and the space's assigned agents.

• Server refusals are undifferentiated — when a create or update is refused, check both the title and the description for duplicates.
• Resetting the deployment token takes effect immediately: any CI pipeline or developer machine still using the old token starts failing on its next deploy — distribute the new value right away (Copy button on the same field).
• The space ID is also the project ID end-user chat clients pass — running an agent against the wrong space ID is refused as agent-not-found, because authorization requires both space access and the agent actually being in that space.
• Partners integrating via webhooks must listen for r_agent (and r_agent_front_settings) in addition to r_space, or they will miss agent entry/active changes.
• Views elsewhere in the product converge within a few seconds of a change rather than instantly — if a freshly edited space looks stale somewhere, give it a moment before assuming the change failed.
• Space views only show whether an agent has settings — the actual values (which can be large) are viewed and edited on each agent's dedicated settings pages.