Sub-organizations

A single flat organization stops working once you have departments with genuinely separate budgets, or a parent company with subsidiaries. Sub-organizations (v0.47) give you a hierarchy with cryptographic isolation between branches.

• Each sub-org can inherit billing from the parent or manage its own.
• Permissions are granted and revoked explicitly per sub-org.
• Sub-orgs can generate their own wallets.
• Users are added per sub-org, so access does not leak sideways.

1. 1

   Create a sub-org.

   bash Copy

   curl -s -X POST https://api.1claw.co/v1/org/sub-orgs \
     -H "Authorization: Bearer $ONECLAW_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"Research","inherit_billing":true}'

2. 2

   Grant it a scoped set of permissions.

   bash Copy

   curl -s -X POST https://api.1claw.co/v1/org/sub-orgs/$SUBORG_ID/permissions \
     -H "Authorization: Bearer $ONECLAW_TOKEN" \
     -d '{"permissions":["vaults:read","agents:create"]}'

3. 3

   Add a user to it.

   bash Copy

   curl -s -X POST https://api.1claw.co/v1/org/sub-orgs/$SUBORG_ID/users \
     -H "Authorization: Bearer $ONECLAW_TOKEN" \
     -d '{"email":"researcher@example.com"}'

4. 4

   Generate wallets scoped to the sub-org.

   bash Copy

   curl -s -X POST https://api.1claw.co/v1/org/sub-orgs/$SUBORG_ID/wallets/generate \
     -H "Authorization: Bearer $ONECLAW_TOKEN" \
     -d '{"chains":["ethereum"]}'

5. 5

   Manage the whole lifecycle from the CLI.

   bash Copy

   1claw sub-org list
   1claw sub-org get $SUBORG_ID
   1claw sub-org archive $SUBORG_ID

Where this goes wrong in practice. Hierarchies are created for isolation and then eroded for convenience.

• Permissions are granted at the parent for expedience. A grant made once at the top to unblock someone dissolves the boundary the hierarchy was created to draw.
• Sub-orgs are used for what the Platform API does. Modelling your product's end users as sub-orgs works until you need per-user claim flows and billing, and by then migration is expensive.
• Archived sub-orgs are assumed gone. Archiving preserves history deliberately, so anything counting active resources needs to account for them.
• Wallet quotas are forgotten. Sub-org wallets count toward the org quota, and a per-sub-org wallet strategy consumes it faster than anyone plans for.