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

# Create API Key

> Mint a scoped API key for a child account. The plaintext key is returned exactly once.

Mints a new API key for a child. Use your **parent** key with `accounts.write`. The child then authenticates its own requests with the returned key.

<Warning>
  The plaintext `key` is returned **exactly once**, in this response. Store it immediately — it cannot be retrieved later, only [rotated](/api-reference/v2/accounts/rotate-api-key) or [revoked](/api-reference/v2/accounts/revoke-api-key).
</Warning>

## Path Parameters

<ParamField path="child_id" type="integer" required>
  The child account's `accountId`.
</ParamField>

## Body Parameters

<ParamField body="name" type="string" required>
  A label for the key (e.g. `prod`, `staging`). Max 255 characters.
</ParamField>

<ParamField body="permissions" type="array" default={["api.full"]}>
  A list of `resource.action` permission strings. The requested set must be a **subset** of the calling parent key's own permissions. Sensitive resources (`admin`, `system`, `billing`, `account`, `accounts`, `users`, `keys`, `api_keys`, `internal`, `root`, `super`) and the wildcard `*` can never be granted.
</ParamField>

<Note>
  Partner-minted keys are **live** keys. To get a sandbox key, create one from the dashboard (see [Sandbox & Testing](/api-reference/v2/sandbox)).
</Note>

## Response Fields

<ResponseField name="apiKey" type="object">
  The created key. Includes `id`, `accountId`, `name`, `key` (**plaintext, once**), `keyPrefix`, `status`, `permissions`, `resourceConstraints`, `expiresAt`, `allowedIps`, `rateLimitOverride`, `sandbox`, `createdAt`, and `lastUsedAt`.
</ResponseField>

<ResponseField name="message" type="string">
  A reminder to store the plaintext key now.
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.tracklysms.com/api/v2/accounts/children/1042/api-keys \
    -H "X-Api-Key: trk_your_parent_key" \
    -H "Content-Type: application/json" \
    -d '{ "name": "prod", "permissions": ["api.full"] }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://api.tracklysms.com/api/v2/accounts/children/1042/api-keys",
      headers={"X-Api-Key": "trk_your_parent_key"},
      json={"name": "prod", "permissions": ["api.full"]},
  )
  key = resp.json()["apiKey"]["key"]  # store this now — shown once
  ```
</RequestExample>

<ResponseExample>
  ```json Success (201) theme={null}
  {
    "apiKey": {
      "id": "66b0f7c84a1d4b2e9c3a1f2e",
      "accountId": 1042,
      "name": "prod",
      "key": "trk_ab12cd34ef56gh78ij90kl12mn34op56",
      "keyPrefix": "trk_ab12",
      "status": "active",
      "permissions": ["api.full"],
      "resourceConstraints": {},
      "expiresAt": null,
      "allowedIps": [],
      "rateLimitOverride": null,
      "sandbox": false,
      "createdAt": "2026-07-26T14:05:00.000000",
      "lastUsedAt": null
    },
    "message": "Store the plaintext key now — it cannot be retrieved later."
  }
  ```
</ResponseExample>

## Error Codes

| HTTP Status | Error Code                        | Description                                                                                       |
| ----------- | --------------------------------- | ------------------------------------------------------------------------------------------------- |
| 400         | `missing_name`                    | `name` is required.                                                                               |
| 400         | `name_too_long`                   | `name` exceeds 255 characters.                                                                    |
| 400         | `invalid_permission`              | A permission is malformed, not a subset of the caller's grant, or references a reserved resource. |
| 400         | `key_cap_exceeded`                | The child already has 25 active keys.                                                             |
| 403         | `constrained_key_cannot_delegate` | The calling key carries IP or resource constraints and cannot mint keys.                          |
| 403         | `api_key_has_no_owner`            | The calling key has no owning user to attribute the mint to.                                      |
| 404         | `child_not_found`                 | No child with that ID under this parent.                                                          |
| 409         | `child_deleted`                   | The child has been deleted.                                                                       |

Also `403 not_a_parent_account` / `insufficient_scope` / `sandbox_read_only`.