# Subkeys

> Create separately funded 7API API keys for teammates or customers. Move balance in and out, track spend per key and revoke instantly with the /v1/subkeys API.


A subkey is a separate API key funded from your balance. Give it to a teammate, a client or one of your own apps. It works exactly like a normal key, with the same base URL and models. Its spending is tracked separately, and you can take back unused balance or shut it off at any time.

- Funding a subkey **moves** money from your balance into the subkey. Nothing is charged for the move.
- The subkey holder can't see your key, your balance or other subkeys, and can't create subkeys.
- The minimum to create a subkey is **$2**. An account can have up to **200** active subkeys.
- Each subkey gets **60 requests per minute** and **16 concurrent requests**. All your subkeys share a separate total of **600 requests per minute** and **128 concurrent requests**, independent of your main key's [rate limit](https://7api.st/docs/rate-limits).

You can manage subkeys in the [dashboard](https://7api.st/subkeys) or through the API with your **main** key.

## Create

```bash
curl https://7api.st/v1/subkeys \
  -H "Authorization: Bearer YOUR_MAIN_KEY" -H "Content-Type: application/json" \
  -d '{"amount_usd": 5, "label": "client-acme"}'
```

```json
{ "object": "subkey", "id": "sub_1234", "label": "client-acme", "api_key": "sk-…",
  "revoked": false, "balance_usd": 5, "spent_usd": 0, "parent_balance_usd": 15 }
```

`label` is optional. It's for your own reference and can be up to 64 characters.

## List and inspect

```bash
curl https://7api.st/v1/subkeys -H "Authorization: Bearer YOUR_MAIN_KEY"
curl https://7api.st/v1/subkeys/sub_1234 -H "Authorization: Bearer YOUR_MAIN_KEY"
```

## Top up and withdraw

```bash
curl https://7api.st/v1/subkeys/sub_1234/topup \
  -H "Authorization: Bearer YOUR_MAIN_KEY" -H "Content-Type: application/json" -d '{"amount_usd": 10}'

# Omit the body to withdraw everything
curl -X POST https://7api.st/v1/subkeys/sub_1234/withdraw \
  -H "Authorization: Bearer YOUR_MAIN_KEY" -H "Content-Type: application/json" -d '{"amount_usd": 3}'
```

## Revoke

```bash
curl -X DELETE https://7api.st/v1/subkeys/sub_1234 -H "Authorization: Bearer YOUR_MAIN_KEY"
```

The key stops working immediately, and any remaining balance returns to you.

## Errors

| Status and code | Meaning |
|---|---|
| `400 amount_below_minimum` | New subkeys need at least $2. |
| `400 invalid_amount` | Send a positive `amount_usd`. |
| `402 insufficient_balance` | Your main balance is too low. |
| `402 insufficient_subkey_balance` | You tried to withdraw more than the subkey holds. |
| `404 subkey_not_found` | The ID is wrong, or the subkey belongs to another account. |
| `409 subkey_busy` | A request on the subkey is in progress. Retry in a few seconds. |
| `409 subkey_revoked` | The subkey was already deleted. |
| `409 subkey_limit` | The account already has 200 active subkeys. |
