> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations

Manage B3OS workspaces, members, roles, API keys, service accounts, workflows, connectors, wallets, and databases.

An organization is the security, billing, credential, wallet, database, and workflow boundary in B3OS. Most resources belong to an organization and are evaluated against organization permissions.

## Organization Resources

| Resource         | Description                                                              |
| ---------------- | ------------------------------------------------------------------------ |
| Workflows        | Drafts, live versions, runs, execution state, visibility, and templates  |
| Members          | Human users with organization roles                                      |
| API keys         | Scoped machine credentials for REST API access                           |
| Service accounts | Non-human identities for automation and backend access                   |
| Connectors       | Encrypted provider credentials and masked metadata                       |
| Wallets          | Organization signing surfaces for EVM, Solana, and wallet-backed actions |
| Databases        | Organization-scoped tables for workflow queries                          |
| Knowledge        | Organization context used by Caddie                                      |
| Restrictions     | Organization policy and usage controls                                   |

## Roles

| Role        | Typical access                                                                                                                                                 |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `owner`     | Full organization control, member management, billing-sensitive controls, workflow publishing, wallet withdrawal, restrictions, and all developer capabilities |
| `developer` | Build and operate workflows, read organization resources, use connectors and runs, manage many workflow resources, and execute most non-owner operations       |

**Permission checks are explicit**

API routes and app flows check permissions such as workflow read/update/execute/publish, connector
  read/create/update/delete, run read/cancel/stream, execution read/stream, database read/update, API key management,
  Caddie chat, and organization operations.

## API Key Scopes

API keys are intended for backend services and automation.

| Scope        | Use                                                                                                                                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `read`       | Read organization, workflow, connector, run, execution, restriction, API key, and database state                                                                                                             |
| `read-write` | Create and update workflows, execute and publish workflows, manage connectors, cancel runs, use execution streams, send Caddie chat, manage API keys and service accounts, and update organization databases |

**API keys are shown once**

Store newly created API keys in your secret manager. B3OS stores hashes and cannot show the raw key again.

## Service Accounts

Use service accounts when a system, backend, or scheduled external job needs an identity distinct from a human user. Pair service accounts with narrow API key scopes and clear ownership.

## Workflow Visibility

| Visibility       | Use                                                       |
| ---------------- | --------------------------------------------------------- |
| `private`        | Individual or restricted workflow authoring               |
| `org`            | Team-visible workflows                                    |
| `public_view`    | Public portfolio, demo, or reference workflow             |
| `public_execute` | Public workflow execution surface with constrained inputs |

## Operational Checklist

**Create roles before inviting broadly**

Keep initial access small until workflows, connectors, wallet policy, and API scopes are understood.
  **Use API keys for servers**

Do not use personal browser sessions from backend services.
  **Review connector ownership**

Rotate or remove connector credentials when provider access changes.
  **Separate public workflows**

Keep public execution workflows narrow, validated, and isolated from broad internal automations.
  **Audit failed runs**

Repeated failures can pause workflows and may indicate provider, schema, wallet, or CU issues.