docs/ts/primitives/secrets.md
Wouldn't it be nice to store secret values like API keys, database passwords, and private keys directly in the source code? Of course, we can’t do that – it's horrifyingly insecure! (Unfortunately, it's also very common.)
Encore's built-in secrets manager makes it simple to store secrets in a secure way and lets you use them in your program like regular variables.
<GitHubLink href="https://github.com/encoredev/examples/tree/main/ts/simple-event-driven" desc="Simple event driven example that uses secrets to store an API key" />
To use a secret in your application, define a top-level variable directly in your code by calling the secret function from encore.dev/config.
For example:
import { secret } from "encore.dev/config";
// Personal access token for deployments
const githubToken = secret("GitHubAPIToken");
// Then, resolve the secret value by calling `githubToken()`.
When you've defined a secret in your program, the Encore compiler will check that they are set before running or deploying your application.
When running your application locally, if a secret is not set, you will get a warning notifying you that a secret value is missing.
When deploying to a cloud environment, all secrets must be defined, otherwise the deploy will fail.
Once you've provided values for all secrets, call the secret as a function. For example:
async function callGitHub() {
const resp = await fetch("https:///api.github.com/user", {
credentials: "include",
headers: {
Authorization: `token ${githubToken()}`,
},
});
// ... handle resp
}
Secret keys are globally unique for your whole application. If multiple services use the same secret name they both receive the same secret value at runtime.
</Callout>The simplest way to set up secrets is with the Secrets Manager in the Encore Cloud Dashboard. Open your app in the Encore Cloud dashboard, go to Settings in the main navigation, and then click on Secrets in the settings menu.
From here you can create secrets, save secret values, and configure different values for different environments.
If you prefer, you can also set up secrets from the CLI using:
encore secret set --type <types> <secret-name>
<types> defines which environment types the secret value applies to. Use a comma-separated list of production, development, preview, and local. Shorthands: prod, dev, pr.
For example encore secret set --type prod SSHPrivateKey sets the secret value for production environments,
and encore secret set --type dev,preview,local GitHubAPIToken sets the secret value for development, preview, and local environments.
In some cases, it can be useful to define a secret for a specific environment instead of an environment type.
You can do so with encore secret set --env <env-name> <secret-name>. Secret values for specific environments
take precedence over values for environment types.
Each secret can only have one secret value for each environment type. For example: If you have a secret value that's shared between development, preview and local, and you want to override the value for local, you must first edit the existing secret and remove local using the Secrets Manager in the Encore Cloud dashboard. You can then add a new secret value for local. The end result should look something like the picture below.
When setting secrets via the encore secret set command, they are automatically synced to all developers
working on the same application, courtesy of the Encore Platform.
In some cases, however, you want to override a secret only for your local machine.
This can be done by creating a file named .secrets.local.cue in the root of your Encore application,
next to the encore.app file.
The file contains key-value pairs of secret names to secret values. For example:
GitHubAPIToken: "my-local-override-token"
SSHPrivateKey: "custom-ssh-private-key"
When you store a secret Encore stores it encrypted using Google Cloud Platform's Key Management Service (KMS).
encore run.