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

# Managing Sub-Accounts

> Update credit limits, manage API keys, and monitor sub-account spending

<Warning>
  All endpoints under `/v1/sub-accounts` require a **main account** API key. A sub-account API key calling these endpoints receives `HTTP 403`. Sub-accounts can read their own balance via `GET /v1/balance`.
</Warning>

## List Sub-Accounts

<CodeGroup>
  ```typescript TypeScript theme={null}
  const { items, nextCursor } = await zavu.subAccounts.list({
    limit: 50,
  });

  for (const sub of items) {
    console.log(`${sub.name}: $${(sub.totalSpent / 100).toFixed(2)} spent`);
  }
  ```

  ```python Python theme={null}
  response = zavu.sub_accounts.list(limit=50)

  for sub in response.items:
      print(f"{sub.name}: ${sub.total_spent / 100:.2f} spent")
  ```

  ```bash cURL theme={null}
  curl https://api.zavu.dev/v1/sub-accounts?limit=50 \
    -H "Authorization: Bearer zv_live_xxx"
  ```
</CodeGroup>

## Update a Sub-Account

Update the name, credit limit, external ID, metadata, or status:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const { subAccount } = await zavu.subAccounts.update("jx7abc123def456", {
    creditLimit: 200000, // Increase to $2,000
    metadata: { plan: "enterprise-plus" },
  });
  ```

  ```python Python theme={null}
  sub_account = zavu.sub_accounts.update(
      "jx7abc123def456",
      credit_limit=200000,
      metadata={"plan": "enterprise-plus"},
  )
  ```

  ```bash cURL theme={null}
  curl -X PATCH https://api.zavu.dev/v1/sub-accounts/jx7abc123def456 \
    -H "Authorization: Bearer zv_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "creditLimit": 200000,
      "metadata": { "plan": "enterprise-plus" }
    }'
  ```
</CodeGroup>

### Updatable Fields

| Field         | Type            | Description                                           |
| ------------- | --------------- | ----------------------------------------------------- |
| `name`        | string          | Sub-account display name                              |
| `externalId`  | string          | Your reference ID                                     |
| `creditLimit` | integer \| null | Spending cap in cents. Set to `null` or `0` to remove |
| `metadata`    | object          | Arbitrary key-value data                              |
| `status`      | string          | `"active"` or `"inactive"`                            |

## Monitor Spending

### Check a Sub-Account's Balance

<CodeGroup>
  ```typescript TypeScript theme={null}
  const balance = await zavu.subAccounts.getBalance("jx7abc123def456");

  console.log(`Team balance: $${(balance.balance / 100).toFixed(2)}`);
  console.log(`Sub-account spent: $${(balance.totalSpent / 100).toFixed(2)}`);
  console.log(`Credit limit: $${(balance.creditLimit / 100).toFixed(2)}`);
  ```

  ```bash cURL theme={null}
  curl https://api.zavu.dev/v1/sub-accounts/jx7abc123def456/balance \
    -H "Authorization: Bearer zv_live_xxx"
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "balance": 150000,
  "currency": "usd",
  "creditLimit": 100000,
  "totalSpent": 45000,
  "isSubAccount": true
}
```

### Check Balance from the Sub-Account's Perspective

When a sub-account uses its own API key to call `GET /v1/balance`, it sees the team balance plus its own spending data:

```bash theme={null}
curl https://api.zavu.dev/v1/balance \
  -H "Authorization: Bearer zv_live_sub_xxxxxxxxxxxx"
```

```json theme={null}
{
  "balance": 150000,
  "currency": "usd",
  "creditLimit": 100000,
  "totalSpent": 45000,
  "isSubAccount": true
}
```

## Manage API Keys

Each sub-account can have multiple API keys. Create additional keys or revoke compromised ones.

### List API Keys

<CodeGroup>
  ```typescript TypeScript theme={null}
  const { items } = await zavu.subAccounts.listApiKeys("jx7abc123def456");

  for (const key of items) {
    console.log(`${key.name} (${key.keyPrefix}...): ${key.environment}`);
  }
  ```

  ```bash cURL theme={null}
  curl https://api.zavu.dev/v1/sub-accounts/jx7abc123def456/api-keys \
    -H "Authorization: Bearer zv_live_xxx"
  ```
</CodeGroup>

### Create an API Key

<CodeGroup>
  ```typescript TypeScript theme={null}
  const { apiKey } = await zavu.subAccounts.createApiKey("jx7abc123def456", {
    name: "Production Key",
    environment: "live",
  });

  // Save this — only shown once
  console.log("New key:", apiKey.key);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.zavu.dev/v1/sub-accounts/jx7abc123def456/api-keys \
    -H "Authorization: Bearer zv_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{"name": "Production Key", "environment": "live"}'
  ```
</CodeGroup>

<Warning>
  The full API key is only returned once in the creation response. Store it securely.
</Warning>

### Revoke an API Key

<CodeGroup>
  ```typescript TypeScript theme={null}
  await zavu.subAccounts.revokeApiKey("jx7abc123def456", "key_id_here");
  ```

  ```bash cURL theme={null}
  curl -X DELETE https://api.zavu.dev/v1/sub-accounts/jx7abc123def456/api-keys/key_id_here \
    -H "Authorization: Bearer zv_live_xxx"
  ```
</CodeGroup>

Revoked keys stop working immediately.

## Suspend a Sub-Account

Set a sub-account's status to `inactive` to temporarily block all messaging without revoking API keys:

```bash theme={null}
curl -X PATCH https://api.zavu.dev/v1/sub-accounts/jx7abc123def456 \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive"}'
```

Re-activate later by setting `status` back to `"active"`.

## Next Steps

<CardGroup cols={2}>
  <Card title="Deletion & Deactivation" icon="trash" href="/guides/sub-accounts/deletion">
    Permanently deactivate sub-accounts
  </Card>

  <Card title="Sub-Accounts Concept" icon="book" href="/concepts/sub-accounts">
    Understand the billing model and architecture
  </Card>
</CardGroup>