Skip to main content
Truefoundry makes it easy to store and manage the secrets for your deployed applications. Secrets are used to store sensitive information like API keys, database passwords, which you can then refer to in your code. Truefoundry integrates with different secret managers like AWS SSM, GCP Secret Manager, HashiCorp Vault, Azure Vault, etc and allows you to store the secrets in them.
When you save a secret using Truefoundry’s UI, the actual secrets are stored in your SecretManager and Truefoundry never stores the secret with itself. You will then get a fqn (fully-qualified-name) for your secret which you can then use in your deployments.
To save secrets in Truefoundry, we need to first integrate a secret manager with Truefoundry.

​
Creating and Managing Secrets

In a project, you likely have a set of secrets associated with it. Managing access to each individual secret can become cumbersome. Hence, we have the concept of secret groups which lets you organize and manage related secrets for a specific project. Within a Secret Group, you can easily add, remove, and update secrets. You can configure access control on each secret group and grant users/teams read, write or admin access. You can check the demo below on how to add a secret group and some secrets in the group.
There are 3 roles in Secret groups:
  • Secret Group Admin: Can create, edit and delete secrets in the group.
  • Secret Group Editor: Can edit and delete secrets in the group and also see the secret values.
  • Secret Group Viewer: Can only see the secret keys, but not the values.
By default, a tenant admin has access to all secret groups. For tenant members and teams you need to assign roles for each secret group.

​
Using the Secrets

Each secret will have a fully-qualified-name (FQN) next to the secret using which you can refer to and use the secret in the places mentioned below. The secret FQN can be used for the following usecases:
You can mount secrets as a volume in your deployments.
You can use the secret FQN in YAMLs which helps enable Gitops for integrations and deployments.

​
Secret Management API

This document describes how to manage secrets using API

​
Overview

The TrueFoundry API allows you to create and manage secret groups, which are collections of key-value pairs stored securely. Secret groups can be created, searched, and updated through REST API endpoints.

​
Prerequisites

Before using the Secret Management API, ensure you have:
  1. TrueFoundry API Server URL: <control-plane-url>/api/svc
  2. API Key: Set the TFY_API_KEY environment variable for authentication

​
API Endpoints

​
1. Create or Update Secret Group

Creates a new secret group or updates an existing one. Endpoint: PUT /v1/secret-groups Refer Headers: 
Authorization: Bearer <TFY_API_KEY>
Content-Type: application/json
Accept: application/json
Request Body: 
{
  "manifest": {
    "name": "secret-group-name",
    "type": "secret-group",
    "integration_fqn": "internal:aws:aws-1:secret-store:internal-secret-store",
    "collaborators": [
      {
        "role_id": "secret-group-admin",
        "subject": "user:email@example.com"
      },
      {
        "role_id": "secret-group-editor",
        "subject": "team:team-name"
      }
    ]
  }
}
Manifest Fields:
  • name (string, required): Name of the secret group. If the name is 5 characters or less, it’s recommended to append -tenant suffix.
  • type (string, required): Always set to "secret-group"
  • integration_fqn (string, required): Integration fully qualified name. Default: "internal:aws:aws-1:secret-store:internal-secret-store"
  • collaborators (array, required): List of collaborators with their roles
    • role_id (string): Role identifier ("secret-group-admin" or "secret-group-editor")
    • subject (string): Subject in format "user:email@example.com" or "team:team-name" Response:
{
  "data": {
    "id": "secret-group-id",
    "name": "secret-group-name",
    ...
  }
}
Example: 
curl -X PUT "${TRUEFOUNDRY_API_SERVER_URL}/v1/secret-groups" \
  -H "Authorization: Bearer ${TFY_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "manifest": {
      "name": "my-tenant",
      "type": "secret-group",
      "integration_fqn": "internal:aws:aws-1:secret-store:internal-secret-store",
      "collaborators": [
        {
          "role_id": "secret-group-admin",
          "subject": "user:admin@example.com"
        },
        {
          "role_id": "secret-group-editor",
          "subject": "team:tenant-secret-access"
        }
      ],
      "ownedBy": {
        "account": "root-account"
      }
    }
  }'

​
2. Add Secrets to Secret Group

Adds secrets (key-value pairs) to an existing secret group. Endpoint: PUT /v1/secret-groups/{secret_group_id} Refer Path Parameters:
  • secret_group_id (string, required): The ID of the secret group returned from the create operation
Headers: 
Authorization: Bearer <TFY_API_KEY>
Content-Type: application/json
Request Body: 
{
  "secrets": [
    {
      "key": "SECRET_KEY_1",
      "value": "secret-value-1"
    },
    {
      "key": "SECRET_KEY_2",
      "value": "secret-value-2"
    }
  ]
}
Secrets Array:
  • Each object in the secrets array contains:
    • key (string, required): The secret key/name
    • value (string, optional): The secret value
      Note Even if updating value of one of the secret in secret group, you need to pass the keys for all other secrets. For eg, if i just want to update value of SECRET_KEY_1 to secret-value-1-updated, the payload would be following:
{
  "secrets": [
    {
      "key": "SECRET_KEY_1",
      "value": "secret-value-1"
    },
    {
      "key": "SECRET_KEY_2"
    }
  ]
}
If the key is missing in the payload, that secret will be deleted from the secret group. Example: 
curl -X PUT "${TRUEFOUNDRY_API_SERVER_URL}/v1/secret-groups/{secret_group_id}" \
  -H "Authorization: Bearer ${TFY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "secrets": [
      {
        "key": "DATABASE_PASSWORD",
        "value": "my-secure-password"
      },
      {
        "key": "API_KEY",
        "value": "sk-1234567890"
      }
    ]
  }'

​
3. Search Secret Groups

Searches for existing secret groups by fqn. Endpoint: GET /v1/secret-groups?fqn={fqn} Refer Query Parameters:
  • fqn (string, required): Use FQN to search for a specific secret group. Format <tenant-name>:<secret-group-name>
Headers: 
Authorization: Bearer <TFY_API_KEY>
Accept: application/json
Response: 
{
  "data": [
    {
      "id": "secret-group-id",
      "name": "secret-group-name",
      "associatedSecrets": [
        {
          "name": "SECRET_KEY_1"
        },
        {
          "name": "SECRET_KEY_2"
        }
      ],
      ...
    }
  ]
}
Example: 
curl -X GET "${TRUEFOUNDRY_API_SERVER_URL}/v1/secret-groups?fqn=my-tenant:my-secret-group" \
  -H "Authorization: Bearer ${TFY_API_KEY}" \
  -H "Accept: application/json"