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

# Sub-Orgs

> Group users and resources under sub-orgs within your organization.

A **Sub)** is a subdivision of your PrimeVault organization that groups the users and resources belonging to a customer or business unit. It lets you manage access to each group separately while keeping everything under one parent organizationA **SubOrg (sub-org-Org** is a subdivision of your PrimeVault organization that groups the users and resources belonging to a customer or business unit. It lets you manage access to each group separately while keeping everything under one parent organizationA **Sub-Org** is a subdivision of your PrimeVault organization that groups the users and resources belonging to a customer or business unit. It lets you manage access to each group separately while keeping everything under one parent organization.

Create and list sub-orgs within the authenticated API user's organization. The external API currently exposes collection creation and listing only.

## Access and permissions

Requests must use an active API user with the ADMIN or OWNER role. The organization and acting user are derived from authentication; caller-supplied organization or user identifiers cannot change the scope.

<CardGroup cols={2}>
  <Card title="Create a SubOrg" icon="plus" href="/accounts-and-wallets/sub-orgs/create-sub-org" />

  <Card title="List SubOrgs" icon="list" href="/accounts-and-wallets/sub-orgs/list-sub-orgs" />
</CardGroup>

## Data models

Both SDKs provide `CreateSubOrgRequest`, `SubOrg`, `SubOrgListResponse`, and `SubOrgControlMode`.

### CreateSubOrgRequest

Contains one required field: `name: string`. It has no `controlMode` field.

### SubOrg

<ResponseField name="id" type="string (UUID)">
  SubOrg identifier.
</ResponseField>

<ResponseField name="orgId" type="string (UUID)">
  Owning organization.
</ResponseField>

<ResponseField name="name" type="string">
  SubOrg name.
</ResponseField>

<ResponseField name="controlMode" type="SubOrgControlMode | null">
  Read-only metadata. New SubOrgs created here return `MANAGED`.
</ResponseField>

<ResponseField name="createdAt" type="string (date-time)">
  Creation timestamp.
</ResponseField>

<ResponseField name="updatedAt" type="string (date-time)">
  Last update timestamp.
</ResponseField>

<ResponseField name="isDeleted" type="boolean">
  Deletion flag. Listed rows are not deleted.
</ResponseField>

The response does not expose `type`, `status`, or `parentSubOrgId`. Python response attributes keep the same camelCase field names as the JSON response.

### SubOrgListResponse

<ResponseField name="results" type="SubOrg[]">
  SubOrgs on the current page.
</ResponseField>

<ResponseField name="nextCursor" type="string | null">
  Cursor for the next page, or null at the end.
</ResponseField>

<ResponseField name="hasNext" type="boolean">
  Whether another page is available.
</ResponseField>

### SubOrgControlMode

The response enum contains `MANAGED` and `INDEPENDENT`; existing data can also return null. These are response values, not creation options. This API always creates with `MANAGED` and rejects caller-supplied control mode.

## SDK method reference

| Operation | JavaScript | Python | Returns |
| - | - | - | - |
| Create | `createSubOrg` | `create_sub_org` | `SubOrg` |
| List | `getSubOrgs` | `get_sub_orgs` | `SubOrgListResponse` |

Both list methods accept optional name filters in params, a limit that defaults to 20, and a cursor. JavaScript methods return promises. Python methods return dataclass instances; `controlMode` is parsed as `SubOrgControlMode` when non-null.

## Errors and supported operations

| Status | When it occurs |
| - | - |
| 400 Bad Request | Missing or invalid name, duplicate name, any supplied controlMode, unsupported MAIN creation, or an invalid pagination cursor. |
| 401 Unauthorized | Missing or invalid authentication, or an inactive API user. |
| 403 Forbidden | A role other than ADMIN/OWNER; an unavailable or non-active assigned home; or creation without organization-wide access. |

Only GET and POST on `/api/external/sub_orgs/` are available. There are no external retrieve-by-ID, update, delete, or embedded-user actions in this section's API.

Create and list sub-orgs within the authenticated API user's organization. The external API currently exposes collection creation and listing only.

## Access and permissions

Requests must use an active API user with the ADMIN or OWNER role. The organization and acting user are derived from authentication; caller-supplied organization or user identifiers cannot change the scope.

<CardGroup cols={2}>
  <Card title="Create a SubOrg" icon="plus" href="/accounts-and-wallets/sub-orgs/create-sub-org" />

  <Card title="List SubOrgs" icon="list" href="/accounts-and-wallets/sub-orgs/list-sub-orgs" />
</CardGroup>

## Data models

Both SDKs provide `CreateSubOrgRequest`, `SubOrg`, `SubOrgListResponse`, and `SubOrgControlMode`.

### CreateSubOrgRequest

Contains one required field: `name: string`. It has no `controlMode` field.

### SubOrg

<ResponseField name="id" type="string (UUID)">
  SubOrg identifier.
</ResponseField>

<ResponseField name="orgId" type="string (UUID)">
  Owning organization.
</ResponseField>

<ResponseField name="name" type="string">
  SubOrg name.
</ResponseField>

<ResponseField name="controlMode" type="SubOrgControlMode | null">
  Read-only metadata. New SubOrgs created here return `MANAGED`.
</ResponseField>

<ResponseField name="createdAt" type="string (date-time)">
  Creation timestamp.
</ResponseField>

<ResponseField name="updatedAt" type="string (date-time)">
  Last update timestamp.
</ResponseField>

<ResponseField name="isDeleted" type="boolean">
  Deletion flag. Listed rows are not deleted.
</ResponseField>

The response does not expose `type`, `status`, or `parentSubOrgId`. Python response attributes keep the same camelCase field names as the JSON response.

### SubOrgListResponse

<ResponseField name="results" type="SubOrg[]">
  SubOrgs on the current page.
</ResponseField>

<ResponseField name="nextCursor" type="string | null">
  Cursor for the next page, or null at the end.
</ResponseField>

<ResponseField name="hasNext" type="boolean">
  Whether another page is available.
</ResponseField>

### SubOrgControlMode

The response enum contains `MANAGED` and `INDEPENDENT`; existing data can also return null. These are response values, not creation options. This API always creates with `MANAGED` and rejects caller-supplied control mode.

## SDK method reference

| Operation | JavaScript | Python | Returns |
| - | - | - | - |
| Create | `createSubOrg` | `create_sub_org` | `SubOrg` |
| List | `getSubOrgs` | `get_sub_orgs` | `SubOrgListResponse` |

Both list methods accept optional name filters in params, a limit that defaults to 20, and a cursor. JavaScript methods return promises. Python methods return dataclass instances; `controlMode` is parsed as `SubOrgControlMode` when non-null.

## Errors and supported operations

| Status | When it occurs |
| - | - |
| 400 Bad Request | Missing or invalid name, duplicate name, any supplied controlMode, unsupported MAIN creation, or an invalid pagination cursor. |
| 401 Unauthorized | Missing or invalid authentication, or an inactive API user. |
| 403 Forbidden | A role other than ADMIN/OWNER; an unavailable or non-active assigned home; or creation without organization-wide access. |

Only GET and POST on `/api/external/sub_orgs/` are available. There are no external retrieve-by-ID, update, delete, or embedded-user actions in this section's API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.