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

# Sub-Accounts Overview

> Create isolated messaging accounts for your customers with independent API keys

Sub-accounts let you provision **isolated messaging environments** for each of your customers. Each sub-account gets its own API key, usage tracking, and optional spending cap — while all charges are billed to your team's balance.

## Quick Start

<Steps>
  <Step title="Create a sub-account">
    ```bash theme={null}
    curl -X POST https://api.zavu.dev/v1/sub-accounts \
      -H "Authorization: Bearer zv_live_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Client ABC",
        "externalId": "client_123",
        "creditLimit": 100000
      }'
    ```
  </Step>

  <Step title="Save the API key">
    The response includes the sub-account's API key. **This is only shown once.**

    ```json theme={null}
    {
      "subAccount": {
        "id": "jx7abc123def456",
        "name": "Client ABC",
        "status": "active",
        "totalSpent": 0,
        "creditLimit": 100000,
        "apiKey": "zv_live_sub_xxxxxxxxxxxx",
        "createdAt": "2025-01-15T10:00:00Z"
      }
    }
    ```
  </Step>

  <Step title="Your customer sends messages">
    Your customer uses their API key to send messages:

    ```bash theme={null}
    curl -X POST https://api.zavu.dev/v1/messages \
      -H "Authorization: Bearer zv_live_sub_xxxxxxxxxxxx" \
      -d '{"to": "+14155551234", "text": "Hello from Client ABC!"}'
    ```
  </Step>
</Steps>

## Guides

<CardGroup cols={2}>
  <Card title="Creating Sub-Accounts" icon="plus" href="/guides/sub-accounts/creating">
    Provision sub-accounts with credit limits, external IDs, and metadata
  </Card>

  <Card title="Managing Sub-Accounts" icon="sliders" href="/guides/sub-accounts/managing">
    Update settings, rotate API keys, and monitor spending
  </Card>

  <Card title="Deletion & Deactivation" icon="trash" href="/guides/sub-accounts/deletion">
    Deactivate sub-accounts and understand the 14-day deletion grace period
  </Card>
</CardGroup>

## Important Rules

<Warning>
  Each team can have **only one main account**. All additional projects must be created as sub-accounts. If you need a separate main account, create a new team.
</Warning>

* Sub-accounts share the team's **balance** but are fully isolated
* Each sub-account has its own API keys, senders, phone numbers, contacts, and usage tracking
* Credit limits are optional — omit or set to `0` for unlimited spending
* When a credit limit is reached, the sub-account's messages are blocked
* Deactivating a sub-account revokes all its API keys immediately