Secrets & Keys

Every secret belongs to one of four scopes. Reads resolve from most specific to least specific, so you can use the same name across scopes and let context decide the value.

1. Branch — one branch of one repository. Useful for short-lived preview and dev work.
2. Environment — one environment such as production or staging.
3. Source — one code repository.
4. Organization — available everywhere in your organization.

A read for STRIPE_KEY on the main branch of the checkout repository in the production environment checks branch first, then environment, then source, then organization, and returns the first match.

Every secret has a current version and retains its previous versions for a configurable retention window. Reads return the current version by default; callers can request a specific version by label (current, previous) or by version number.

Rotation never takes effect mid-request. A workload that reads STRIPE_KEY at start gets one consistent value for the lifetime of that read.

Create or update a secret with PUT /api/v1/secrets/{name}, read the current version with GET, list organization secrets with GET /api/v1/secrets, and delete with DELETE. Mutating calls require an Idempotency-Key header; retrying with the same key is safe and returns the original result without double-writing. The full surface is documented in the API reference.

• Symmetric keys — AES-256-GCM for encrypt and decrypt.
• Asymmetric signing keys — Ed25519 or ECDSA P-256 for sign and verify. The public key is fetchable and can be handed to external verifiers.
• MAC keys — HMAC-SHA256 for sign and verify when both producer and verifier are yours and a shared secret is acceptable.
• Data keys — generate-data-key returns a fresh symmetric key encrypted under your key, for envelope encryption of large payloads you store yourself.

Key type is fixed at creation. A key created for HMAC cannot later produce asymmetric signatures.

Keys are versioned. Rotating a key creates a new version and makes it current; previous versions remain available for decryption and verification of material produced while they were current. Ciphertexts and signatures carry an explicit version prefix, so rotation never invalidates data at rest.

Set a rotation schedule per key (common choices are 90, 180, or 365 days) or rotate on demand through the API or the dashboard. Schedules can be paused and resumed without losing rotation history.

An alias is a human-friendly pointer to a key. Your application references alias/payments-signer; operations can repoint the alias to a new key during a planned rotation without code changes. Aliases are organization-scoped and follow the same access-control rules as the key they reference.

A secret profile is a named collection of secret references — not the values themselves. A dev-env profile might bundle GITHUB_TOKEN, STRIPE_TEST_KEY, and OPENAI_API_KEY. Create the profile once; attach it to every sandbox that should receive those secrets.

Profiles carry their own access-control grants. A member can be allowed to launch sandboxes with the dev-env profile without being granted direct read on the underlying secrets.

Two surfaces, both materialized at sandbox start:

• Environment variables — process-local. Your code reads process.env.STRIPE_KEY, os.environ["STRIPE_KEY"], or the equivalent in any language. No SDK required.
• /run/secrets/* — files on a RAM-only tmpfs. Use this for SSH private keys, TLS certificates, JSON service-account files, and anything that doesn't fit neatly in an environment variable. The tmpfs never persists and is never written to the sandbox's durable volume.

Certain environment variable names are reserved and cannot be overridden by profiles, including HOME, PATH, runtime-controlled variables used by the sandbox runner, and any name beginning with FORGE_METAL_.

Short-lived workloads pick up the current value at start and run to completion on that value. Long-running sandboxes, including development environments, receive rotation events from Forge Metal and refresh environment variables and tmpfs files in place. Your code can watch for file changes or re-read environment variables on demand; rotation never takes effect mid-request for a read already in progress.

• Secret values are never written to platform state on the sandbox host. Execution records store only secret references, never resolved values.
• Secret values never appear in audit payloads, telemetry, traces, or error messages.
• Workloads from one organization never reach secrets belonging to another, regardless of scope or name overlap.
• Platform-curated sandbox images — the shared base snapshots every customer clones from — never contain customer secrets.

Owners and admins grant specific operations (read, use, rotate) on specific resources to specific actors — members, teams, or service accounts. Grants can be time-boxed and are audited on every use. Revoking a grant takes effect on the next read.

For automated callers such as CI jobs and service accounts, issue API credentials with the exact operations the caller needs. API credentials never inherit blanket role permissions.