> ## 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 Certificate Secret

> Creates a certificate-type secret for use with mTLS-authenticated upstream APIs

## Create Certificate Secret

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

Creates a certificate-type secret for use with mTLS-authenticated upstream APIs. KnoxCall accepts PEM, PKCS#7, CRT/CER, PFX/P12, and KEY formats.

For PEM-format certificates, KnoxCall automatically extracts the subject, issuer, and expiry date and returns them in the response metadata.

### Request Body

| Field                 | Type   | Required | Description                                                                  |
| --------------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `name`                | string | Yes      | Secret name (spaces → underscores)                                           |
| `certificate_content` | string | Yes      | Certificate in PEM, PKCS#7, CRT/CER format, or base64-encoded DER/PFX/P12    |
| `private_key`         | string | No       | PEM-encoded private key to store alongside the certificate                   |
| `passphrase`          | string | No       | Passphrase to decrypt the private key. Encrypted and stored separately       |
| `certificate_type`    | string | No       | `pem` (default), `pfx`, `p12`, `crt`, `cer`, `key`, `pkcs7`, `p7b`, or `p7c` |
| `collection_id`       | uuid   | No       | Assign to a collection                                                       |

### Response

```json theme={"dark"}
{
  "data": {
    "id": "b9e3f0a5-4c6d-5e8f-0f1a-3b5d7e9f1a3b",
    "name": "MY_TLS_CERT",
    "secret_type": "certificate",
    "certificate_type": "pem",
    "base_environment": "production",
    "collection_id": null,
    "metadata": {
      "subject": "CN=example.com, O=Example Inc, C=US",
      "issuer": "CN=Let's Encrypt Authority X3, O=Let's Encrypt, C=US",
      "expires_at": "2026-03-15T12:00:00.000Z",
      "has_private_key": true
    }
  },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
```

<CodeGroup>
  ```bash cURL — PEM with private key theme={"dark"}
  curl -X POST https://api.knoxcall.com/v1/secrets/certificate \
    -H "Authorization: Bearer tk_live_abc123..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "MY_TLS_CERT",
      "certificate_type": "pem",
      "certificate_content": "-----BEGIN CERTIFICATE-----\nMIID...==\n-----END CERTIFICATE-----",
      "private_key": "-----BEGIN PRIVATE KEY-----\nMIIE...==\n-----END PRIVATE KEY-----"
    }'
  ```

  ```bash cURL — PEM CA certificate only theme={"dark"}
  curl -X POST https://api.knoxcall.com/v1/secrets/certificate \
    -H "Authorization: Bearer tk_live_abc123..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "CA_CERT",
      "certificate_type": "pem",
      "certificate_content": "-----BEGIN CERTIFICATE-----\nMIID...==\n-----END CERTIFICATE-----"
    }'
  ```

  ```javascript Node.js theme={"dark"}
  import fs from "fs";

  const cert = fs.readFileSync("client.pem", "utf8");
  const key = fs.readFileSync("client.key", "utf8");

  const resp = await fetch("https://api.knoxcall.com/v1/secrets/certificate", {
    method: "POST",
    headers: {
      Authorization: "Bearer tk_live_abc123...",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: "MY_TLS_CERT",
      certificate_type: "pem",
      certificate_content: cert,
      private_key: key
    })
  });
  const { data: secret } = await resp.json();
  ```
</CodeGroup>

You can also create certificate secrets via `POST /v1/secrets` with `secret_type: "certificate"` and the same body fields.

### Errors

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