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

# Key Skill Binding

> Read or replace the per-key skill allowlist that scopes which skills a key can use.

Each API key can carry an explicit allowlist of skills. An **empty** allowlist means the key inherits all of your installed skills (the default). A **non-empty** allowlist restricts the key to exactly those skills, intersected with your installed set at request time.

## Authentication

Requires an API key with `billing` scope. The caller must be the key owner or a team member with permission to manage API keys.

## Path Parameters

<ParamField path="id" type="string" required>
  The API key UUID.
</ParamField>

## Get the binding

`GET /api/v1/keys/{id}/skills`

<ResponseField name="key_id" type="string">
  The API key UUID.
</ResponseField>

<ResponseField name="inherits_all" type="boolean">
  `true` when the allowlist is empty (the key inherits all installed skills).
</ResponseField>

<ResponseField name="skill_ids" type="string[]">
  The bound skill IDs (empty when `inherits_all` is `true`).
</ResponseField>

<ResponseField name="skills" type="array">
  Display metadata for each bound skill: `id`, `slug`, `name`, `category`, `is_public`.
</ResponseField>

## Replace the binding

`PUT /api/v1/keys/{id}/skills`

<ParamField body="skill_ids" type="string[]" required>
  The full set of skill IDs to bind. Pass an empty array to reset the key to inherit all installed skills.
</ParamField>

Team-scoped keys may only bind skills that are public, authored by the caller, or scoped to the key's team. If any ID isn't visible to the key, the request returns `400 skill_visibility_denied` and no change is made.

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT https://www.hitheo.ai/api/v1/keys/KEY_ID/skills \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "skill_ids": ["11111111-2222-3333-4444-555555555555"] }'
  ```

  ```json Response theme={null}
  {
    "key_id": "KEY_ID",
    "inherits_all": false,
    "skill_ids": ["11111111-2222-3333-4444-555555555555"]
  }
  ```
</CodeGroup>