Secrets

Manage environment variables, encrypted at rest and synced to the sandbox .env.

Secrets are environment variables for your project. They are encrypted at rest and automatically synced to the sandbox .env. Secret values are never returned by the API. Both endpoints require the api-key header.

#Create Secret

POST/api/v1/vcaas/projects/:projectId/secretsFree

Add an environment variable. Encrypted at rest, auto-synced to the sandbox .env.

Path parameters

Parameter	Type	Description
`projectId`	string	The project ID

Body parameters

Field	Type	Required	Description
`secretName`	string	Yes	Environment variable name
`secretValue`	string	Yes	The secret value, stored encrypted
`environment`	string	No	`"development"` \| `"production"` \| `"both"` (default: `"both"`)

Response fields

Field	Type	Description
`data._id`	string	ID of the created secret
`data.secretName`	string	The secret name
`data.environment`	string	`"development"` \| `"production"` \| `"both"`
`data.createdAt`	string	ISO 8601 creation date

Example request

bash

curl -X POST \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"secretName":"STRIPE_KEY","secretValue":"sk_live_abc123","environment":"both"}' \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/secrets

Success · 200 OK

json

{
  "errors": null,
  "data": {
    "_id": "65f1a2b3c4d5e6f7a8b9c0d1",
    "secretName": "STRIPE_KEY",
    "environment": "both",
    "createdAt": "2026-03-11T10:30:00.000Z"
  }
}

Error · 400

json

{
  "errors": {
    "errorCode": "MISSING_SECRET_FIELDS",
    "errorMessage": "secretName and secretValue are required"
  },
  "data": null
}

Error codes

Code	HTTP	Meaning
`MISSING_PROJECT_ID`	400	projectId is required
`PROJECT_NOT_FOUND`	404	Project does not exist or you don't own it
`MISSING_SECRET_FIELDS`	400	secretName and secretValue are required
`INVALID_SECRET_KEY_NAME`	400	Invalid secret key name format

#Delete Secret

DELETE/api/v1/vcaas/projects/:projectId/secrets/:secretIdFree

Remove an environment variable by ID. The sandbox .env is synced automatically.

Path parameters

Parameter	Type	Description
`projectId`	string	The project ID
`secretId`	string	The secret ID to delete

Response fields

Field	Type	Description
`data.success`	boolean	true on success

Example request

bash

curl -X DELETE -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/secrets/65f1a2b3c4d5e6f7a8b9c0d1

Success · 200 OK

json

{ "errors": null, "data": { "success": true } }

Error · 404

json

{
  "errors": {
    "errorCode": "PROJECT_NOT_FOUND",
    "errorMessage": "Project does not exist or you don't own it"
  },
  "data": null
}

Error codes

Code	HTTP	Meaning
`MISSING_PROJECT_ID`	400	projectId is required
`PROJECT_NOT_FOUND`	404	Project does not exist or you don't own it
`MISSING_SECRET_ID`	400	secretId is required