Secret

A Secret is an object containing sensitive information, or a handle to a secured keypair (such as a general RSA keypair or an SSH keypair).

Scope

A secret can be created in one of the following scopes:

Org level: A secret accessible by all members in the org, or limited to specific groups based on access policy.
Personal: A secret belonging to a user (owner) only, independent of any org. Only the owner can access it. Currently only keypair and SSH keypair kinds are valid for personal secrets.
Private: A secret belonging to a user (owner) but scoped under a specific org. It is only accessible by the owner when working under that org.

Kind

A secret can be created as one of the following kinds:

Secret: Any opaque content considered sensitive. The content is retrieved as-is when accessed.
Keypair: An asymmetric keypair (e.g. RSA). The private key is secured in a vault service and can never be accessed directly. The public key can be accessed freely. The keypair can only be used via internal API for signing, verifying signatures, and encrypting/decrypting data.
SSH Keypair: A special type of keypair used automatically by the system when SSH authentication is needed. See Managed SSH Keypair for details.

Access

The content of a Secret-kind secret can only be accessed in one of the following ways:

Filesystem: On the filesystem of a workspace, under /run/sandbox/fs/secrets.
Environment variable expansion: Expand into an environment variable in the sandbox definition, e.g. GITHUB_TOKEN=${secret:shared-github-token}.
Content templates: Expand in content templates in the sandbox definition, e.g. Login using credential {{secret "ENDPOINT_CREDENTIAL"}}.
Crafting configuration: Certain Crafting configuration fields support referencing a secret by name.

Filesystem Access

Org-level secrets are mounted under both /run/sandbox/fs/secrets/shared and /run/sandbox/fs/secrets/owner.

Private secrets in an org are mounted under /run/sandbox/fs/secrets/owner and override org-level secrets with the same name.

Private secrets are only mounted when the sandbox sharing mode is Private, or they are explicitly listed in Collaborated mode. They are unmounted when the sandbox is in Shared mode.

Org-level secrets marked as not mountable are never mounted in the filesystem.

Org-level secrets marked as admin only are only mounted when the corresponding workspace is in admin-only restriction mode.

Filesystem Example

Given the following org-level secrets:

cred0: content credential 0
cred1: content credential 1

And a private sandbox whose owner has these private secrets:

my-cred: content my special token
cred1: content my credential

The workspace filesystem of the sandbox will contain:

Path	Content
`/run/sandbox/fs/secrets/shared/cred0`	`credential 0`
`/run/sandbox/fs/secrets/shared/cred1`	`credential 1`
`/run/sandbox/fs/secrets/owner/cred0`	`credential 0`
`/run/sandbox/fs/secrets/owner/my-cred`	`my special token`
`/run/sandbox/fs/secrets/owner/cred1`	`my credential` (overrides org-level `cred1`)
`/run/sandbox/fs/secrets/owner/default-ssh-0`	The SSH public key of the owner's managed SSH keypair