Skip to main content
Secrets let your Notion Workers use API keys, tokens, client secrets, webhook signing secrets, and other credentials without committing those values to your source code. Notion encrypts worker secrets at rest and exposes them as environment variables at runtime. In your worker code, read them from process.env. 
const apiKey = process.env.OPENWEATHER_API_KEY;
Never commit .env files or any type of secret to source control. Worker projects created from the template include .env and .env.* in .gitignore by default.

​
Add a secret

Use ntn workers env set to store one or more secrets for your worker: 
ntn workers env set OPENWEATHER_API_KEY=your-secret
To set multiple secrets at once, pass multiple KEY=value pairs: 
ntn workers env set GITHUB_CLIENT_ID=your-client-id GITHUB_CLIENT_SECRET=your-client-secret
If a key already exists, setting it again replaces the previous value.
Quote values that contain spaces, shell metacharacters, or other characters your shell might interpret.

​
Use a secret in worker code

Read secrets from process.env inside your worker capability: 
worker.tool("getWeather", {
  title: "Get Weather",
  description: "Fetch the current weather for a city",
  schema: {
    type: "object",
    properties: {
      city: { type: "string" },
    },
    required: ["city"],
    additionalProperties: false,
  },
  execute: async ({ city }) => {
    const apiKey = process.env.OPENWEATHER_API_KEY;

    if (!apiKey) {
      throw new Error("OPENWEATHER_API_KEY is not configured");
    }

    const response = await fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${encodeURIComponent(
        city,
      )}&appid=${apiKey}`,
    );

    return response.json();
  },
});

​
Pull secrets for local development

When you run a worker locally, use a .env file to provide the same environment variables that the hosted worker receives. Pull remote secrets into .env: 
ntn workers env pull
Or write to a different file: 
ntn workers env pull --file=.env.local
If the file already exists, pull preserves comments, blank lines, and local-only keys. It updates keys that also exist remotely, then appends new remote keys. For non-interactive scripts, add --yes to skip the confirmation prompt: 
ntn workers env pull --yes
Treat any pulled .env file as sensitive. Confirm that the file is ignored by Git before you pull secrets into a project.

​
Push local secrets to your worker

If you’ve added secrets locally to .env, push them to the hosted worker: 
ntn workers env push
Or push a different file: 
ntn workers env push --file=.env.local
push adds new local keys and updates changed local keys. It does not remove keys that exist only in the remote worker environment. For non-interactive scripts, add --yes: 
ntn workers env push --yes

​
Manage another worker

When you run these commands inside a worker project, the CLI reads the worker ID from workers.json. To manage a different worker, pass its worker ID. For set and unset, use --worker-id: 
ntn workers env set --worker-id <worker-id> API_KEY=your-secret
ntn workers env unset --worker-id <worker-id> API_KEY
For list, pull, and push, pass the worker ID as the positional argument: 
ntn workers env list <worker-id>
ntn workers env pull <worker-id>
ntn workers env push <worker-id>

​
Use secrets for OAuth client credentials

For custom OAuth providers, store the OAuth client ID and client secret as worker secrets: 
ntn workers env set GITHUB_CLIENT_ID=xxx GITHUB_CLIENT_SECRET=yyy
Then read them from process.env in the OAuth capability configuration: 
worker.oauth("githubAuth", {
  name: "github-oauth",
  authorizationEndpoint: "https://github.com/login/oauth/authorize",
  tokenEndpoint: "https://github.com/login/oauth/access_token",
  scope: "repo user",
  clientId: process.env.GITHUB_CLIENT_ID ?? "",
  clientSecret: process.env.GITHUB_CLIENT_SECRET ?? "",
});

​
Command summary

CommandWhat it does
ntn workers env set KEY=valueStores or replaces one or more secrets
ntn workers env listLists secret keys without revealing values
ntn workers env unset KEYRemoves a secret
ntn workers env pullWrites remote secrets to a local .env file
ntn workers env pushAdds or updates remote secrets from a local .env file
See the CLI command reference for all ntn workers env flags and options.

​
Next steps

OAuth

Authenticate with third-party APIs using OAuth.

Syncs

Sync external data into Notion databases.

Agent tools

Build custom tools for Notion AI.

Webhooks

Receive HTTP events from external services.