Skip to main content
To use your own secret store with TrueFoundry, you add a Generic Secret Store integration. This guide walks you through adding the integration, describes each form field, and documents the API contract your secret server must implement so TrueFoundry can list, get, create, update, and delete secrets.

​
Generic Secret Server Overview

Generic Secret Service lets you connect your own secret storage server to TrueFoundry. Secrets stay in your infrastructure while TrueFoundry communicates with your server over a simple HTTP API. You can use Header Auth (e.g., API key or bearer token) so that all requests from TrueFoundry are authenticated. The secret mount path is fixed (default: tfy-secret) and is not configurable in the form.

​
Generic Secret Integration

To add a Generic Secret integration:
  1. Go to the Platform > Integration Providers page in the TrueFoundry UI.
  2. Click on ‘Add Integration Provider’.
  3. Select ‘Custom’ as the provider type.
  4. Choose ‘Generic Secret Store’ in the integrations section.
  5. Fill out the form fields as shown below:
Generic Secret Store Integration Form

​
Field Descriptions

  • Name: The name of the integration provider account (required).
  • Custom Basic Auth (Optional): Toggle to enable or disable custom basic authentication for the provider.
  • Display Name: The name of the integration that will be displayed in the TrueFoundry UI (required).
  • Base URL: The base URL of your generic secret server (e.g., https://your-secret-server.example.com). Required for the integration to communicate with your secret storage service.
  • Header Auth: Static API key or token authentication via request headers. All users share the same credentials. Use this to authenticate requests to your generic secret server.
  • Headers: Key-value pairs passed to the generic secret server with every request (e.g., an API key header). Add one or more headers using + Add Headers. Both key and value are required for each header.
  • Access Control (Optional): List of subjects authorized to access this integration. Use user FQN in the format <user_type>:<username>. By default, can be set to everyone.
The secret mount path is fixed at tfy-secret and is not configurable in the form. Your server must expose secrets under this path for the integration to work.

​
Path and Naming Rules

  • The root path is always tfy-secret.
  • Each secret key is built from a fully qualified name (FQN) by replacing colons with slashes.
Example: The secret acme:prod:db-password is stored at path tfy-secret/acme/prod/db-password.

​
API Contract (Required Endpoints)

Your secret server must expose the following endpoints. The Base URL you configure is the server root; all paths below are relative to it. The headers you set in Header Auth are sent on every request.
MethodPathPurpose
PUT/secretsCreate or update a secret
GET/secrets?path=<key>Read a secret (latest version)
GET/secrets?path=<key>&version=<versionId>Read a specific version
DELETE/secretsDelete a secret or a specific version

​
PUT /secrets — Create or update secret

Creates a new secret or a new version of an existing secret at the given path. Request
  • Content-Type: application/json
  • Body: JSON object with required fields:
FieldTypeRequiredDescription
pathstringYesFull secret path (e.g. tfy-secret/acme/prod/db-password)
valuestringYesThe secret value to store
Request example: 
{
  "path": "tfy-secret/acme/prod/db-password",
  "value": "my-secret-value"
}
Response
  • Status: 2xx on success
  • Body: Must include version. If missing, TrueFoundry reports a server error.
Response example: 
{
  "path": "tfy-secret/acme/prod/db-password",
  "version": 1
}

​
GET /secrets — Read secret

Returns the secret value for the given path. Use optional version to read a specific version. Request
  • Query parameters:
ParameterTypeRequiredDescription
pathstringYesFull secret path (e.g. tfy-secret/acme/prod/db-password)
versionnumber or stringNoVersion to read; omit for latest
  • Example: GET /secrets?path=tfy-secret/acme/prod/db-password
  • With version: GET /secrets?path=tfy-secret/acme/prod/db-password&version=1
Response
  • Status: 200 on success; 404 if the secret or path is not found
  • Body: Must include value. If missing, TrueFoundry reports a server error.
Response example: 
{
  "value": "<secret-value>"
}

​
DELETE /secrets — Delete secret

Deletes a secret. Send only path to delete all versions, or include version to delete a single version. Request
  • Content-Type: application/json
  • Body: JSON object.
Option 1 — Delete all versions:
FieldTypeRequiredDescription
pathstringYesFull secret path
Request example (delete all versions): 
{
  "path": "tfy-secret/acme/prod/db-password"
}
Option 2 — Delete one version:
FieldTypeRequiredDescription
pathstringYesFull secret path
versionnumberYesVersion number to delete
Request example (delete one version): 
{
  "path": "tfy-secret/acme/prod/db-password",
  "version": 2
}
Response
  • Status: 2xx on success; 400 if path or version does not exist.

​
Response Requirements

  • Write (PUT): The response must include a version field. If it is missing, TrueFoundry reports a server error.
  • Read (GET): The response must include a value field. If it is missing, TrueFoundry reports a server error.

​
Validation and Auth Notes

  • When you save the integration, TrueFoundry checks connectivity by calling GET /secrets?path=tfy-secret. Your server must respond successfully (e.g. 200) for validation to pass.
  • Header Auth headers are sent on all secret operations (GET, PUT, DELETE). Ensure your server accepts and validates these headers for every request.

​
Quick Test with curl

You can verify your secret server from the command line. Replace these placeholders with your own values:
PlaceholderReplace with
BASE_URLYour integration Base URL (e.g. https://your-secret-server.example.com)
HEADER_NAMEThe header name from Header Auth (e.g. X-API-Key or Authorization)
HEADER_VALUEThe header value from Header Auth
tfy-secret/acme/prod/db-passwordAny valid path under your root (optional; this is just an example)
Run the commands in order: create a secret, read it back, then delete it.
1. Create or update a secret (PUT) Sends a JSON body with path and value. Your server should respond with a JSON object that includes version. 
curl -X PUT "BASE_URL/secrets" \
  -H "Content-Type: application/json" \
  -H "HEADER_NAME: HEADER_VALUE" \
  -d '{"path":"tfy-secret/acme/prod/db-password","value":"my-secret-value"}'
Expected: HTTP 2xx and a JSON response containing "version" (e.g. {"path":"...","version":1}).
2. Read a secret (GET) Requests the secret by path. Use the same path you used in step 1. 
curl "BASE_URL/secrets?path=tfy-secret/acme/prod/db-password" \
  -H "HEADER_NAME: HEADER_VALUE"
Expected: HTTP 200 and a JSON response containing "value" (e.g. {"value":"my-secret-value"}).
3. Delete a secret (DELETE) Sends a JSON body with path to delete the secret (all versions). 
curl -X DELETE "BASE_URL/secrets" \
  -H "Content-Type: application/json" \
  -H "HEADER_NAME: HEADER_VALUE" \
  -d '{"path":"tfy-secret/acme/prod/db-password"}'
Expected: HTTP 2xx with no body or a simple success payload.

​
Troubleshooting

SymptomLikely cause
Error like “path must start with …”Root path mismatch. TrueFoundry uses tfy-secret as the root; your server must use the same.
”Missing “value"" or “Missing “version""Response shape mismatch. Ensure GET returns { "value": "..." } and PUT returns { "version": ... }.
404 when saving the integrationValidation failed: GET /secrets?path=tfy-secret could not reach the server or the path does not exist. Ensure the root path is available.

​
Final Steps

  • After filling all required fields, click Add Integration Provider to save your integration.
  • You can then use this integration as a secret store when configuring your applications in TrueFoundry.