Secrets

Notebooks

The Secrets feature makes it easier to securely access private data and APIs in Observable notebooks. Secrets are name-value pairs, similar to environment variables, that you can specify in your workspace settings, and they are available to use by all members in your workspace.

You can also choose whether to share each secret with members of guest roles in your workspace via the Allow guest access option when creating or updating a secret. Secrets are always unshared with guests by default.

Note

Guest users have access to any secret enabled with Allow guest access. Access is not governed by the notebooks shared with them.

The Secrets page in the Notebooks area.

For example, say you want to talk to the Cloudflare API. Add a secret named CLOUDFLARE_API_KEY whose value is your API key (here 0123456789abcdef, which for obvious reasons is not a real key). To access your key from a notebook, say:

Secret("CLOUDFLARE_API_KEY") // returns 0123456789abcdef

The Secret function takes a single argument, the name of the secret, and returns the value of the corresponding secret if it exists. If the secret doesn’t exist, then the Secret function instead throws an error.

Secret("DOES_NOT_EXIST") // throws an error

Only private notebooks (which are only readable by members of your workspace) can access your secrets—that’s why they’re secret! If you share or publish a notebook, it won’t be able to access secrets: any cell that references the Secret function will error.

You must explicitly grant permission for a notebook to access your secrets. The first time you ask for a secret from your private notebook, you’ll see a confirmation dialog asking for permission to access your secrets. This extra step protects you when you fork or import someone else’s notebook into your private notebook. If you don’t trust the code, don’t give it your secrets!