Skip to main content

​
Create Secret

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 and Create Certificate Secret.
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.

​
String Secret

FieldTypeRequiredDescription
namestringYesDisplay name for the secret (spaces → underscores)
valuestringYesThe secret value to encrypt and store
collection_iduuidNoAssign to a collection
expires_atstringNoISO-8601 datetime after which the secret is considered expired
strict_expiry_enforcementbooleanNoIf true, injection is blocked when the secret is expired. Defaults to false (warn-only)

​
Response

{
  "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" }
}

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_..."
  }'

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"]

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();

​
Errors

StatusTypeDescription
400validation_errorMissing required fields or invalid collection
403plan_limitSecret limit reached for your subscription plan
409conflictA secret with this name already exists