> ## 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.

# Create a Sub-Org

> Create a sub-org with a unique name. Requires the ADMIN or OWNER role.

**POST** `/api/external/sub_orgs/`

Create a managed end-user SubOrg in the authenticated organization. Creation requires organization-wide access as described above.

## Request body

<ParamField body="name" type="string" required>
  Non-empty SubOrg name. The name must be unique within the organization.
</ParamField>

## Response

```typescript theme={null}
interface SubOrg {
  id: string;
  orgId: string;
  name: string;
  controlMode: SubOrgControlMode | null;
  createdAt: string;
  updatedAt: string;
  isDeleted: boolean;
  version: number;
}
```

## JavaScript SDK

```typescript theme={null}
const subOrg = await apiClient.createSubOrg({
  name: "PrimeVault customer",
});
console.log(subOrg.id, subOrg.controlMode);
```

## Python SDK

```python theme={null}
from primevault_python_sdk.types import CreateSubOrgRequest

sub_org = api_client.create_sub_org(
    CreateSubOrgRequest(name="PrimeVault customer")
)
print(sub_org.id, sub_org.controlMode)
```

<RequestExample dropdown>
  ```json Request body theme={null}
  {
    "name": "PrimeVault customer"
  }
  ```

  ```bash cURL theme={null}
  # Sample only. Generate a new signed token for each request
  # (see Authentication). Tokens expire after 120 seconds.
  curl --request POST \
    --url "https://api.primevault.com/api/external/sub_orgs/" \
    --header "Authorization: Bearer <signed JWT>" \
    --header "Api-Key: <API key>" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "PrimeVault customer"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json JSON example theme={null}
  {
    "id": "a648fa0d-4ca9-4f4f-a520-7ef5e9db34eb",
    "orgId": "a30d5e99-7076-45da-a933-0d5642619340",
    "name": "PrimeVault customer",
    "controlMode": "MANAGED",
    "createdAt": "2026-09-14T12:00:00Z",
    "updatedAt": "2026-09-14T12:00:00Z",
    "isDeleted": false,
    "version": 1
  }
  ```
</ResponseExample>


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