Skip to main content
An organization owns agents, members, API keys, connections, and the agent templates it publishes, and is the boundary a member’s role applies to. It gives a company, or each client of an agency, one place where people, roles, keys, and installs are governed.

​
What an organization owns

Every agent belongs to one organization. A public agent is reachable by every member through their organization role; a private agent only through a grant on that agent, except by the owner, who keeps access to everything; builders and above switch an agent between the two. Each member gets a personal Space on joining, private to them and supervising the organization’s public agents. A member’s API keys are bound to the organization or to named agents; connections to integrations are personal or shared.

​
The six roles

Roles nest: each includes the one before it. Sensitive permissions (money, secrets, role assignment, key issuance, telephony provisioning) are never implied by a broad grant; a role names them or lacks them. An admin or owner assigns only roles whose permissions they fully hold; only an owner grants owner, and the last owner can’t be downgraded or removed. An invitation goes by email, carries a role on the organization or on named agents (never owner; billing-admin only on the organization), and expires after 2 days; accepting it creates the member’s Space. A grant on one agent gives a role on that agent alone. The admin dashboard’s Admin users page invites by email to the selected agent; its Access page list sets no role, and the invitee joins as viewer. Deactivating a member suspends their grants and revokes their organization-scoped API keys; reactivating restores the grants, not the keys. Removing deletes membership and grants and revokes the same keys. Neither touches the owner, and the last active admin can’t be deactivated.

​
Roles and API keys

A scoped API key carries a role, chosen when it is issued, on each organization or agent it may act on. The issuer may only give a role within their own reach, and every call is checked against both the key’s grants and its owner’s current grants, so demoting, deactivating, or removing the owner narrows or ends the key at once. A key never inherits its owner’s reach into private agents: they are named on the key, by id or as a snapshot taken at issue time, so agents created later are excluded. Keys take an optional expiry; an admin may issue and list keys for another member.
A legacy key acts as its owner in every organization the owner belongs to. For a client, issue a scoped key on that client’s organization only.

​
One credential across client organizations

One user session or key reaches every organization it holds a grant in. lua agents --json --ci lists them all, with each agent’s visibility and your roles on it. lua init --agent-id <id> points a project at one agent; --agent-name <name> --org-id <id> creates an agent in a client organization; --org-name <name> creates an organization with you as owner; --from-agent-id <id> --org-id <id> copies an agent across organizations. A scoped key creates nothing; see What a scoped key cannot do.

​
What an administrator controls

admin and owner also set:
  • Template install policy: an allow-list, a deny-list (deny wins), whether members may browse the public catalog, and an approval mode. Under require-approval a member’s install queues as a request an admin approves or denies, an admin’s own install proceeds, and a blocked install fails with POLICY_BLOCKED; the organization’s own templates are never blocked.
  • Single sign-on: SAML or OIDC for a domain proven with a DNS TXT record. Enforcing it blocks other sign-in methods on those domains. A first sign-in provisions the member with the default role (viewer unless set) or the highest role mapped from the identity provider’s groups, never owner. SCIM 2.0 provisioning and deprovisioning are accepted with a per-organization token; deprovisioning deactivates the member. A domain-join policy (off, allow-all, require-approval) lets verified-domain emails join as viewer.
  • Audit log: SSO and SCIM changes, member provisioning and deprovisioning, API key issuance, template and workflow policy writes, and feature switches, with actor, action, target, and time; read through the API, newest first, up to 200 a page. No file export.
  • Workflow run retention (see Security and data) and archiving the organization, which needs an emailed confirmation code, leaves members, grants, and channels in place, and makes requests to its agents answer ORG_ARCHIVED until restored.

​
Organizations and neighbors

A role is a named bundle of the scopes on the Credentials page: that page maps CLI areas to scopes, this one scopes to roles. A Space is a routing surface, not a permission boundary: connections follow their owner, and a consulted agent runs with its own grants. An agent template’s consent rules travel with it; the install policy belongs to the installing organization.

​
When to use it

  • An agency with several clients: one organization per client, owned by the client. Agency staff hold builder, the client’s operator holds operator, and the agency’s CI holds one scoped key per client organization, so revoking one client touches nothing else. Publish the shared agent as an agent template and install it into each client’s organization under that client’s policy.
  • One company, several departments: one organization; private agents with per-agent grants keep each department’s agents apart.
  • One developer: one organization and a user session; roles start to matter when a second person or a CI key arrives.

​
Limits

​
Next steps

Credentials

User sessions, legacy and scoped keys, and the scope table.

Security and data

The mechanisms behind these controls, and what is not stated.

Agent templates

Publish once, install per client, update with consent.

For operators

What a client operator changes in the dashboard.