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

# Create Secret

> Creates a new encrypted string secret

## Create Secret

```http theme={"dark"}
POST /v1/secrets
```

Creates a new encrypted secret. Pass `secret_type` to choose the variant — the default is `string`.
For type-specific convenience endpoints see [Create OAuth2 Secret](./create-oauth2) and [Create Certificate Secret](./create-certificate).

<Note>
  Secret names are normalized: spaces are replaced with underscores. For example, `"Stripe API Key"` becomes `STRIPE_API_KEY`. The normalized name is returned as both `name` and `shortcode_name`.
</Note>

### String Secret

| Field                       | Type    | Required | Description                                                                                 |
| --------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------- |
| `name`                      | string  | Yes      | Display name for the secret (spaces → underscores)                                          |
| `value`                     | string  | Yes      | The secret value to encrypt and store                                                       |
| `collection_id`             | uuid    | No       | Assign to a collection                                                                      |
| `expires_at`                | string  | No       | ISO-8601 datetime after which the secret is considered expired                              |
| `strict_expiry_enforcement` | boolean | No       | If `true`, injection is blocked when the secret is expired. Defaults to `false` (warn-only) |

### Response

```json theme={"dark"}
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "STRIPE_API_KEY",
    "shortcode_name": "STRIPE_API_KEY",
    "base_environment": "production",
    "environment_count": 1,
    "secret_type": "string",
    "collection_id": null,
    "expires_at": null,
    "strict_expiry_enforcement": false
  },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
```

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.knoxcall.com/v1/secrets \
    -H "Authorization: Bearer tk_live_abc123..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "STRIPE_API_KEY",
      "value": "sk_live_..."
    }'
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.post(
      "https://api.knoxcall.com/v1/secrets",
      headers={
          "Authorization": "Bearer tk_live_abc123...",
          "Content-Type": "application/json"
      },
      json={
          "name": "STRIPE_API_KEY",
          "value": "sk_live_..."
      }
  )
  secret = resp.json()["data"]
  ```

  ```javascript Node.js theme={"dark"}
  const resp = await fetch("https://api.knoxcall.com/v1/secrets", {
    method: "POST",
    headers: {
      Authorization: "Bearer tk_live_abc123...",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: "STRIPE_API_KEY",
      value: "sk_live_..."
    })
  });
  const { data: secret } = await resp.json();
  ```
</CodeGroup>

### Errors

| Status | Type               | Description                                     |
| ------ | ------------------ | ----------------------------------------------- |
| 400    | `validation_error` | Missing required fields or invalid collection   |
| 403    | `plan_limit`       | Secret limit reached for your subscription plan |
| 409    | `conflict`         | A secret with this name already exists          |