SetCloud
✦ Ask AI Get started

Secrets Vault quickstart

Credentials, encrypted and injected. Keep keys out of your repo; read them where they’re needed.

Prerequisites

  • A SetCloud account with billing set up.
  • The CLI installed and logged in (npm install -g ./setcloud-cli-0.2.0.tgz && setcloud login) — or use Secrets Vault in the dashboard. See the CLI quickstart for the archive download.

1. Create a secret

setcloud secrets create prod/api-key "v3rys3cret" --description "Payments API key"

2. Inspect its metadata

setcloud secrets get prod/api-key

Add --json to any secrets command for machine-readable output.

3. Update it — versions are kept

setcloud secrets update prod/api-key "n3wvalue"
setcloud secrets versions list prod/api-key

Every update creates a version. You can move staging labels between versions when you need a controlled cutover.

4. Delete safely

setcloud secrets delete prod/api-key

Deletes get a 7-day recovery window by default — setcloud secrets restore prod/api-key undoes it. --force deletes immediately and permanently.

Deleting a project removes its project-managed credentials, such as its generated database credentials. Secrets you created in Secrets Vault remain with their versions, even when the deleted project was their last link. The project’s links and runtime access are removed. Delete retained secrets separately in Secrets Vault or with the CLI; normal storage billing continues until deletion.

5. Generate strong values

setcloud secrets generate-password --length 40

Read a secret at runtime

Link the secret under your project’s Linked Secrets, then redeploy. Linking grants that workload access; adding or removing a link requires another deployment. Use the secret’s name in your server code rather than putting its value in the repository.

Download the Secrets SDK package and install the archive in your app:

npm install ./setcloud-secrets-0.1.0.tgz

For a linked secret named prod/database containing JSON credentials:

import { getSecret } from '@setcloud/secrets';

const credentials = JSON.parse(await getSecret('prod/database'));
// Pass credentials to your server-side database client. Do not log them.

The deployed app uses its temporary workload identity automatically. You do not supply an account access key, a platform API token, or a secret value to this SDK. It can resolve only the names linked to the project; workload permissions enforce access to the corresponding secrets.

By default, each call fetches the current value, so a rotated value is available on the next read without restarting the app. Existing database connections or clients must still be refreshed by your application when their credentials change. You can opt into a short cache:

import { SecretsClient } from '@setcloud/secrets';

const secrets = new SecretsClient({ cacheTtlMs: 30_000 });
const value = await secrets.getSecret('prod/database');
const latest = await secrets.getSecret('prod/database', { refresh: true });

Use getSecretValue for binary values or version metadata. Reads can select versionId or versionStage; omitting both reads the current version. The SDK is server-side only and needs a deployed SetCloud workload with a linked secret. It does not grant access to a local laptop or a browser bundle.

Use startup environment variables

Linked secrets also support an environment variable such as PAYMENTS_API_KEY. After linking and redeploying, your app can read process.env.PAYMENTS_API_KEY without committing the value or putting it into a build argument.

From a script or AI agent, link and redeploy the same way:

setcloud api POST /api/projects/42/secrets --data '{"envName":"PAYMENTS_API_KEY","secretName":"prod/api-key"}'
setcloud projects redeploy 42

Replace 42 with your project ID. Environment values update when new app instances start; existing container environments and warm serverless instances do not refresh automatically. DATABASE_URL is managed by the platform for projects with a database. Application secrets are not supplied to repository builds; static browser bundles must never contain private credentials.

Management API availability

The authenticated POST /api/secrets management endpoint takes an Action and its parameters. It is separate from the AI Gateway API and from the deployed application’s temporary identity used by the Secrets SDK.

The following management actions currently return HTTP 409 with code FEATURE_UNAVAILABLE:

  • RotateSecret: scheduled rotation integrations are unavailable. Use PutSecretValue for a new value; update the external service’s credentials separately.
  • PutResourcePolicy: custom or external identity grants are unavailable. Use project secret links for application access.
  • ReplicateSecretToRegions, RemoveRegionsFromReplication, and StopReplicationToReplica: additional replica regions and replica changes are unavailable. Requests with AddReplicaRegions are also rejected.

CancelRotateSecret can cancel an existing schedule. Existing policy inspection/removal and policy validation remain available; successful validation does not attach a policy or grant access.

Costs

Secrets bill per secret per month plus a small charge per block of reads — see the pricing page for current rates. Runtime reads are collected into audit and usage records asynchronously, so they can appear after a delay.

Next

Scheduled rotation integrations, custom external access policies, and additional replica regions are not currently available. Use versioned value updates and project secret links for supported credential refresh and access control.