Secret references
OrkStage stores references to secrets, not values. The env and AWS Secrets Manager schemes, JSON keys, emulator settings and where each secret lives.
OrkStage stores references to secrets, never their values, and resolves each reference at the moment it is used. Values are not written to the database, not returned by the API and not logged.
Schemes
| Reference | Resolved from |
|---|---|
env://NAME | An environment variable of the API and worker processes. NAME contains uppercase letters, digits and _. Suits local development and simple installations. |
aws-sm://<name-or-arn> | The SecretString of an AWS Secrets Manager secret. |
aws-sm://<name-or-arn>#<jsonKey> | One string field of a secret that holds JSON. |
env://ORKSTAGE_AWS_PROD_EXTERNAL_ID
aws-sm://orkstage/aws/prod-external-id
aws-sm://arn:aws:secretsmanager:eu-west-1:111122223333:secret:orkstage/targets-AbCdEf#prodExternalIdThe credentialRef of a cloud target must use one of these schemes. The API rejects anything else,
including a pasted secret value.
AWS Secrets Manager
OrkStage reads aws-sm:// secrets with the control plane's own AWS credentials, found through the
default provider chain (ECS task role, EC2 instance profile, SSO or environment). It does not use a
customer's deployment role for this.
| Setting | Default | Meaning |
|---|---|---|
SECRETS_AWS_REGION | us-east-1 | Region for references given by name. ARNs carry their own region. |
SECRETS_AWS_ENDPOINT | Endpoint override for emulators such as MiniStack, as seen from the API and the worker. |
The control plane identity needs secretsmanager:GetSecretValue on the referenced secrets, and
kms:Decrypt when a secret uses a customer managed KMS key.
Values are cached in memory for five minutes, so a deployment with many references does not hit Secrets Manager rate limits. Error messages show the secret name in redacted form and keep only the error class, because AWS SDK messages can include account ids.
Other secrets and where they live
| Secret | Where it lives |
|---|---|
SESSION_SECRET, ENCRYPTION_KEY, ORKSTAGE_LICENSE_KEY, OIDC client secrets | Environment of the API and the worker. Inject them from your secret store. |
Webhook signing secrets (they start with whsec_) | Database, encrypted with ENCRYPTION_KEY. Shown once, when created or rotated. |
| API key tokens | Only their SHA-256 hash is stored. Shown once, when created. |
| Database passwords of provisioned RDS instances | OpenTofu generates them as ephemeral values and passes them through write only attributes to RDS and to a Secrets Manager secret in the customer account. The state holds password: null. Services receive the secret's ARN. |
| AWS credentials for customer accounts | Never stored. Short lived AssumeRole credentials stay in memory and reach one runner container as environment variables. |
Not yet supported
Resolvers for other secret stores (Azure Key Vault, OCI Vault, HashiCorp Vault) will arrive with the matching provider adapters.
Connecting an AWS account
Create the OrkStage deployment role with an external id, prepare the OpenTofu state bucket, then register and validate an AWS account as a cloud target.
OpenTofu runner and state
How OrkStage runs OpenTofu in throwaway containers, keeps one S3 state per resource without secrets, plans before apply and scans for drift.