Secrets

Workspace-scoped secrets are stored encrypted and injected into your deployed function at deploy time as environment bindings. Use them for API keys, database URLs, and other sensitive configuration. Each workspace has its own set of secrets, isolated from other workspaces.

Create or update (POST /secrets)

Create a new secret or update an existing one for an organization (same name overwrites).

curl -X POST https://api.fold.run/secrets \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "STRIPE_KEY",
    "value": "sk_live_..."
  }'

Field	Type	Required	Description
name	string	Yes	Secret name (e.g. STRIPE_KEY, DATABASE_URL)
value	string	Yes	Secret value (stored encrypted)

Response: 201 with id, tenant_id, name, created_at.

Secrets are encrypted at rest using AES-GCM. The platform never returns the secret value over the API.

List (GET /secrets)

List secrets for an organization. Only names (and ids/metadata) are returned; values are never included.

curl "https://api.fold.run/secrets" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: List of { id, tenant_id, name, created_at }.

Delete (DELETE /secrets/:id)

Remove a secret by its ID. Future deploys will no longer include this binding.

curl -X DELETE "https://api.fold.run/secrets/secret_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Version history

Every time you update a secret, the previous value is retained as a version. List versions for a secret:

curl "https://api.fold.run/secrets/STRIPE_KEY/versions" \
  -H "Authorization: Bearer YOUR_TOKEN"

Restore a previous version:

curl -X POST "https://api.fold.run/secrets/STRIPE_KEY/restore/2" \
  -H "Authorization: Bearer YOUR_TOKEN"

After restoring, redeploy to apply the restored value.

Snapshots

Create a named snapshot of all current secrets for backup or rollback:

# Create a snapshot
curl -X POST https://api.fold.run/secrets/snapshots \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "pre-migration" }'

# List snapshots
curl "https://api.fold.run/secrets/snapshots/list" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Restore from a snapshot
curl -X POST "https://api.fold.run/secrets/snapshots/pre-migration/restore" \
  -H "Authorization: Bearer YOUR_TOKEN"

Restoring a snapshot restores each secret to the version captured in the snapshot.

Use in your function

After you add secrets and deploy (or redeploy), your function receives them as environment bindings accessible via env:

export default {
  async fetch(request: Request, env: Record<string, string>) {
    const stripe = new Stripe(env.STRIPE_KEY);
    // ...
    return new Response("OK");
  }
};

Set secrets before deploying so they are included in the next deploy.

Managing via CLI

# Set a secret (prompts for value)
fold secrets set STRIPE_KEY

# Set with value inline
fold secrets set STRIPE_KEY sk_live_...

# List secrets
fold secrets list

# Delete a secret
fold secrets delete STRIPE_KEY

Managing via dashboard

Visit app.fold.run/console/secrets to add, view, and delete secrets through the web UI.

Secrets vs. environment variables

	Secrets	Env vars
Scope	Workspace-wide (all functions in the workspace)	Per-function
Values returned by API	Never	Masked preview
Best for	API keys, tokens, passwords	Config values, endpoints, flags

For per-function configuration, see Environment variables.

Cross-workspace secret sharing

Share a secret from one workspace to another within the same account. This creates a reference — the target workspace can use the secret at deploy time without duplicating the value. Requires the admin role.

Share a secret

curl -X POST https://api.fold.run/workspaces/ws_source/shared-secrets \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_name": "STRIPE_KEY",
    "target_workspace_id": "ws_target"
  }'

Field	Type	Required	Description
secret_name	string	Yes	Name of the secret in the source workspace
target_workspace_id	string	Yes	Workspace to share the secret to

Response (201):

{
  "id": "ss_abc123",
  "source_workspace_id": "ws_source",
  "target_workspace_id": "ws_target",
  "secret_name": "STRIPE_KEY",
  "created_at": "2026-03-24T10:00:00Z",
  "created_by": "user_xyz"
}

List shared secrets

List secrets shared to a workspace:

curl "https://api.fold.run/workspaces/ws_target/shared-secrets" \
  -H "Authorization: Bearer YOUR_TOKEN"

Revoke a shared secret

curl -X DELETE "https://api.fold.run/workspaces/ws_source/shared-secrets/ss_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

After revoking, redeploy functions in the target workspace to remove the secret binding.

API reference

Method	Endpoint	Description
POST	/workspaces/:id/shared-secrets	Share a secret to another workspace
GET	/workspaces/:id/shared-secrets	List secrets shared to this workspace
DELETE	/workspaces/:id/shared-secrets/:secretId	Revoke a shared secret

Best practices

• Set secrets before deploying. Secrets are injected at deploy time. If you add a secret after deploying, redeploy to pick it up.
• Use descriptive names. STRIPE_KEY is better than KEY1. The name becomes the binding name in your code.
• Rotate secrets regularly. Update the secret value via POST (same name overwrites), then redeploy to apply.
• Don't commit secrets to code. Use secrets or env vars instead of hardcoding values in your source code.