---
title: "Create a toolkit — scoped bundle of upstream API credentials with a client API key"
method: POST
path: "/toolkits"
tags: ["toolkits"]
---

# Create a toolkit — scoped bundle of upstream API credentials with a client API key

`POST /toolkits`

Creates a toolkit: a named bundle of upstream API credentials with a scoped client API key for the agent.
Returns a toolkit API key (tk_xxx) — shown once, not recoverable.
Bind credentials via POST /toolkits/{id}/credentials.
Set access policy via PUT /toolkits/{id}/credentials/{cred_id}/permissions.
Agents use toolkit keys to call the broker; only bound credentials are injected.

## Request body

- ToolkitCreate — Create a new toolkit with scoped credentials and access control. Optionally generates first API key.
  - `name` string, required — Toolkit name for identification
  - `description` string, nullable — Optional description of this toolkit's purpose
  - `simulate` boolean — If true, toolkit operates in dry-run mode (no real API calls)
  - `initial_key_label` string, nullable — Label for the first key created with this toolkit (e.g. 'Agent A')
  - `initial_key_allowed_ips` string[], nullable — IP allowlist for the first key. NULL = unrestricted.

## Response `201`

Successful Response

- ToolkitOut — Toolkit configuration with scoped credentials and access control policies.
  - `id` string, required — Toolkit ID
  - `name` string, required — Human-readable toolkit name
  - `description` string, nullable — Optional description of this toolkit's purpose
  - `created_at` number, nullable — Unix timestamp when created
  - `disabled` boolean — If true, all API keys for this toolkit are revoked
  - `key_count` integer, nullable — Number of API keys issued for this toolkit
  - `credential_count` integer, nullable — Number of credentials bound to this toolkit
  - `keys` ToolkitKeyOut[] — API keys for this toolkit (if expanded)
    - `id` string, required — Key ID (format: ck_{8chars})
    - `name` string, nullable — User-assigned key name for identification
    - `prefix` string, nullable — Key prefix (always 'tk_' for toolkit keys)
    - `allowed_ips` string[], nullable — IP CIDR ranges allowed to use this key (null = no IP restriction)
    - `revoked` boolean — True if this key has been revoked and can no longer authenticate
    - `created_at` number, nullable — Unix timestamp when key was created
  - `credentials` CredentialBindingOut[] — Credentials bound to this toolkit (if expanded)
    - `credential_id` string, required — Credential ID (format: cred_{12chars})
    - `label` string, nullable — User-assigned credential label
    - `api_id` string, nullable — API ID this credential is for
    - `auth_type` string, nullable — Auth scheme type: bearer, basic, apiKey, oauth2, etc
  - `permissions` object[] — Access control rules for this toolkit

## Other responses

- `422` — Validation Error

## Changes

- **2026-04-13** `76e8f6063728` — 6 breaking, 9 warning, 23 info
  - media type `application/problem+json` was changed to a more general media type `application/json` for the response status `422`
  - the response property `detail` became optional for the status `422`
  - the `detail` response property's maxLength was unset from `4096` for the response status `422`
  - the `detail` response's property type changed from `string` to `array` for status `422`
  - …34 more

[Change history](https://skmtc.dev/jentic/apis/jentic-control-plane-api/changes/toolkits/post.md)

---

[API](https://skmtc.dev/jentic/apis/jentic-control-plane-api.md) · [All operations](https://skmtc.dev/jentic/apis/jentic-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/jentic/jentic-control-plane-api/revisions/bd463fcefb14/schema)