Secrets are encrypted credentials (API keys, passwords, OAuth2 connections, certificates) that KnoxCall injects into proxied requests at runtime. Secret values are never exposed to callers — they are stored encrypted and injected server-side.
The Client API intentionally does not expose secret values. You can create secrets and update their values, but you cannot read the decrypted value back through the API. Use the KnoxCall Dashboard to view secret values. Secret Types KnoxCall supports three types of secrets:
Type Description stringAny static value — API keys, tokens, passwords, connection strings oauth2OAuth2 connection with automatic token refresh. KnoxCall handles the full token lifecycle. certificateTLS/mTLS certificate with optional private key, for use with mTLS-authenticated upstream APIs
List Secrets Returns a paginated list of secrets with metadata only (no values).
Query Parameters Parameter Type Default Description pageinteger 1Page number per_pageinteger 20Items per page (max 100) sortstring nameSort by: created_at, name, or base_environment orderstring ascSort direction: asc or desc
Response { "data" : [ { "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "name" : "STRIPE_API_KEY" , "shortcode_name" : "STRIPE_API_KEY" , "base_environment" : "production" , "secret_type" : "string" , "collection_id" : null , "created_at" : "2026-01-15T09:30:00.000Z" , "environment_count" : 3 } ], "meta" : { "total" : 12 , "page" : 1 , "per_page" : 20 , "total_pages" : 1 , "request_id" : "550e8400-e29b-41d4-a716-446655440000" } }
curl "https://api.knoxcall.com/v1/secrets?sort=name&order=asc" \ -H "Authorization: Bearer tk_live_abc123..."
Get Secret Returns metadata for a single secret. The encrypted value is not included.
Path Parameters Parameter Type Description iduuid The secret ID
Response { "data" : { "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "name" : "STRIPE_API_KEY" , "shortcode_name" : "STRIPE_API_KEY" , "base_environment" : "production" , "secret_type" : "string" , "collection_id" : null , "created_at" : "2026-01-15T09:30:00.000Z" , "environment_count" : 3 }, "meta" : { "request_id" : "550e8400-e29b-41d4-a716-446655440000" } }
Errors Status Type Description 404 not_foundSecret not found
Create Secret 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 Field Type Required Description namestring Yes Display name for the secret (spaces → underscores) valuestring Yes The secret value to encrypt and store collection_iduuid No Assign to a collection
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 }, "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_..." }'
Errors Status Type Description 400 validation_errorMissing required fields or invalid collection 403 plan_limitSecret limit reached for your subscription plan 409 conflictA secret with this name already exists
Create OAuth2 Secret Creates an OAuth2-type secret. KnoxCall stores the OAuth2 configuration encrypted at rest and manages token refresh automatically.
After creation, complete the authorization flow by redirecting your user to the redirect_uri returned in the response. For non-interactive grant types (client_credentials, password), tokens are fetched immediately without any redirect.
Supported providers: google, github, salesforce, microsoft, slack, customFor custom providers, you must supply auth_url and token_url.
OAuth2 secrets require a Pro or Enterprise plan.
Request Body Field Type Required Description namestring Yes Secret name (spaces → underscores) providerstring Yes OAuth2 provider: google, github, salesforce, microsoft, slack, or custom client_idstring Yes OAuth2 client ID from your provider’s developer console client_secretstring Conditional OAuth2 client secret. Required unless using mtls_certificate_id or grant_type: implicit grant_typestring No authorization_code (default), client_credentials, password, or implicitscopesstring[] No OAuth2 scopes to request. Defaults to the provider’s recommended scopes auth_urlstring No Authorization endpoint URL. Required for custom provider token_urlstring No Token endpoint URL. Required for custom provider usernamestring Conditional Username for password grant type passwordstring Conditional Password for password grant type mtls_certificate_iduuid No ID of a certificate-type secret for mTLS auth to the token endpoint collection_iduuid No Assign to a collection
Response { "data" : { "id" : "a7c1d8f3-2e4b-4c6a-8d9e-1f3b5a7c9d2e" , "name" : "GOOGLE_OAUTH" , "secret_type" : "oauth2" , "provider" : "google" , "redirect_uri" : "https://api.knoxcall.com/auth/oauth2/callback/a7c1d8f3-..." , "connection_status" : "not_connected" , "base_environment" : "production" , "collection_id" : null , "mtls_certificate_id" : null }, "meta" : { "request_id" : "550e8400-e29b-41d4-a716-446655440000" } }
Register the returned redirect_uri as an authorized redirect URL in your OAuth2 provider’s app settings before redirecting users through the authorization flow.
cURL — Authorization Code (Google)
cURL — Client Credentials (Salesforce)
cURL — Custom Provider
Node.js
curl -X POST https://api.knoxcall.com/v1/secrets/oauth2 \ -H "Authorization: Bearer tk_live_abc123..." \ -H "Content-Type: application/json" \ -d '{ "name": "GOOGLE_OAUTH", "provider": "google", "client_id": "1234567890.apps.googleusercontent.com", "client_secret": "GOCSPX-abc123", "scopes": ["openid", "email", "profile"] }'
You can also create OAuth2 secrets via POST /v1/secrets with secret_type: "oauth2" and the same body fields.
Errors Status Type Description 400 validation_errorMissing required fields, invalid provider, or mTLS certificate not found 403 plan_limitOAuth2 secrets require Pro or Enterprise plan, or secret limit reached 409 conflictA secret with this name already exists
Create Certificate Secret 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 namestring Yes Secret name (spaces → underscores) certificate_contentstring Yes Certificate in PEM, PKCS#7, CRT/CER format, or base64-encoded DER/PFX/P12 private_keystring No PEM-encoded private key to store alongside the certificate passphrasestring No Passphrase to decrypt the private key. Encrypted and stored separately certificate_typestring No pem (default), pfx, p12, crt, cer, key, pkcs7, p7b, or p7ccollection_iduuid No Assign to a collection
Response { "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" } }
cURL — PEM with private key
cURL — PEM CA certificate only
Node.js
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-----" }'
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_errorMissing required fields or invalid certificate_type 403 plan_limitSecret limit reached for your subscription plan 409 conflictA secret with this name already exists
Update Secret Value PUT /v1/secrets/:id/value
Replaces the encrypted value of an existing string secret. You can target a specific environment to set an environment-specific override.
Path Parameters Parameter Type Description iduuid The secret ID
Query Parameters Parameter Type Default Description environmentstring Base environment Target a specific environment
Request Body Field Type Required Description valuestring Yes The new secret value
Response { "data" : { "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "name" : "STRIPE_API_KEY" , "environment" : "production" }, "meta" : { "request_id" : "550e8400-e29b-41d4-a716-446655440000" } }
Errors Status Type Description 400 validation_errorMissing value field 404 not_foundSecret not found
Delete Secret Permanently deletes a secret and all of its environment-specific values.
Path Parameters Parameter Type Description iduuid The secret ID
Response { "data" : { "deleted" : true }, "meta" : { "request_id" : "550e8400-e29b-41d4-a716-446655440000" } }
Errors Status Type Description 404 not_foundSecret not found 409 in_useSecret is currently assigned to one or more routes
You cannot delete a secret that is in use by a route. Remove the secret from all routes first, then delete it.
Get OAuth2 Access Token GET /v1/secrets/:id/oauth2/token
For OAuth2-type secrets, returns the current access token. If the token has expired, KnoxCall will automatically refresh it before returning.
Path Parameters Parameter Type Description iduuid The secret ID (must be an OAuth2-type secret)
Query Parameters Parameter Type Default Description environmentstring Base environment Target a specific environment
Response { "data" : { "access_token" : "eyJhbGciOiJSUzI1NiIs..." , "expires_at" : "2026-03-10T15:30:00.000Z" , "token_type" : "Bearer" , "connection_status" : "connected" }, "meta" : { "request_id" : "550e8400-e29b-41d4-a716-446655440000" } }
Errors Status Type Description 400 invalid_typeSecret is not an OAuth2 type 404 not_foundSecret not found 500 token_errorFailed to retrieve or refresh the OAuth2 token
