> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Organizations and roles
> What an organization owns, the six member roles, how a role bounds an API key, and how one credential works across client organizations
An organization owns [agents](/concepts/agents), members, [API keys](/concepts/credentials), connections, and the [agent templates](/concepts/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](/concepts/spaces) 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](/concepts/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.
| Role | Adds |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `viewer` | Read everything that isn't sensitive |
| `operator` | Conversations and takeover; [channel](/concepts/channels) sends; support; evals; document templates; start, approve, and read [workflow](/concepts/workflows) runs |
| `builder` | Agents, every primitive, workflows; knowledge; channel management; integrations; Spaces; telephony and provisioning; provider keys; commerce |
| `admin` | Members: invite, assign roles, deactivate, remove; organization settings, SSO, audit log; members' API keys |
| `owner` | Billing and credits; the organization's creator and principal; alone may grant `owner` |
| `billing-admin` | Read everything that isn't sensitive, plus billing, credits, usage; a side branch off the ladder |
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`](/reference/cli/agents-and-models) lists them all, with each agent's `visibility` and your roles on it. [`lua init --agent-id `](/reference/cli/init) points a project at one agent; `--agent-name --org-id ` creates an agent in a client organization; `--org-name ` creates an organization with you as owner; `--from-agent-id --org-id ` copies an agent across organizations. A scoped key creates nothing; see [What a scoped key cannot do](/concepts/credentials#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](/concepts/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
| Item | Value |
| ---------------------------------------------- | -------------------------------- |
| System roles | 6; custom roles can't be created |
| Invitation validity | 2 days |
| Grants per API key | 100 |
| Agents in an `all-current` key selection | 100 |
| Organizations `lua agents` lists on an API key | 100 |
| Audit log page | 1 to 200 entries; default 50 |
| Template allow-list and deny-list | 500 ids each |
## Next steps
User sessions, legacy and scoped keys, and the scope table.
The mechanisms behind these controls, and what is not stated.
Publish once, install per client, update with consent.
What a client operator changes in the dashboard.