How to Use Environment Variables in PocketBase Hooks

API keys, webhook secrets, and third-party credentials should never be hardcoded
inside your PocketBase hooks.

Instead of writing this:

const apiKey = "re_live_your_real_secret";

you can store the value as an environment variable in PocketBase Cloud and read
it only when your server-side hook runs.

In this tutorial, you will:

• add an environment variable from the PocketBase Cloud dashboard;
• access it from a PocketBase JavaScript hook;
• verify that the variable is available without exposing its value; and
• update or remove it later.

Prerequisites

Before starting, you need:

• a PocketBase Cloud account;
• a project with a running PocketBase instance; and
• access to the Hooks and Environment Variables pages for that instance.

You do not need SSH access to the server, and you do not need to upload a
.env file manually.

Open the Environment Variables page

Sign in to the PocketBase Cloud dashboard and follow these steps:

1. Open Projects.
2. Select your project.
3. Open the PocketBase instance you want to configure.
4. Select Environment Variables from the instance sidebar.

This page lists the environment variables attached to the selected PocketBase
instance.

Add an environment variable

Select Add Variable.

For this tutorial, create the following example variable:

Key: RESEND_API_KEY
Value: re_your_example_key

Use a fake value while testing. Never include a real API key in screenshots,
public repositories, support messages, or blog posts.

Environment variable keys must:

• start with an uppercase letter or underscore;
• contain only uppercase letters, numbers, and underscores; and
• not contain spaces.

Examples of valid keys include:

RESEND_API_KEY
STRIPE_SECRET_KEY
DISCORD_WEBHOOK_URL
INTERNAL_API_TOKEN

Select Add Variable to save it. PocketBase Cloud synchronizes the variable
with the instance and restarts the PocketBase service so that the new value is
available to hooks.

The restart may take a few seconds.

Read the variable from a PocketBase hook

PocketBase JavaScript hooks do not run in Node.js. They run in PocketBase's
embedded JavaScript runtime, so process.env.RESEND_API_KEY is not the correct
API here.

Use PocketBase's $os.getenv() helper instead:

const apiKey = $os.getenv("RESEND_API_KEY");

$os.getenv() returns the current value as a string. If the variable does not
exist, it returns an empty string.

You can find more information in the
PocketBase JavaScript overview and
the $os.getenv() reference.

Create a hook to verify the configuration

Return to your PocketBase instance and open Hooks from the sidebar.

Create a file named:

env-check.pb.js

Add the following code:

routerAdd("GET", "/api/env-check", (e) => {
  const apiKey = $os.getenv("RESEND_API_KEY");

  return e.json(200, {
    configured: !!apiKey,
  });
});

This route only reports whether the variable exists. It does not return the
secret itself.

Save the hook and make sure it is active.

Test the hook

Call the new route using your PocketBase instance domain:

curl https://YOUR_POCKETBASE_DOMAIN/api/env-check

If the variable is configured, the response will be:

{
  "configured": true
}

The response confirms that the hook can access the variable without sending
the secret to the client.

Use the variable in a real hook

After confirming that the variable is available, you can use it when calling a
third-party API.

The following example shows the general pattern:

routerAdd("POST", "/api/send-message", (e) => {
  const apiKey = $os.getenv("RESEND_API_KEY");

  if (!apiKey) {
    throw new InternalServerError(
      "The email service is not configured",
    );
  }

  const response = $http.send({
    url: "https://api.example.com/v1/messages",
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message: "Hello from PocketBase",
    }),
  });

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

Replace the example URL and request body with the API you are integrating.

The important part is that the credential comes from $os.getenv() instead
of appearing in the hook source.

Update an environment variable

To rotate a credential or change its value:

1. Return to Environment Variables.
2. Select Add Variable.
3. Enter the existing key, such as RESEND_API_KEY.
4. Enter the new value and save it.

Saving an existing key updates its value. After the PocketBase instance
restarts, hooks will read the new value automatically. You do not need to
change the hook source.

Delete an environment variable

To remove a variable, select the delete button next to its key and confirm the
action.

Your hook should always handle a missing variable safely:

const apiKey = $os.getenv("RESEND_API_KEY");

if (!apiKey) {
  throw new InternalServerError(
    "The email service is not configured",
  );
}

This produces a controlled error instead of allowing the hook to make an
invalid request with an empty credential.

Troubleshooting

The endpoint returns configured: false

Check the following:

• The key in the dashboard is exactly RESEND_API_KEY.
• The key passed to $os.getenv() uses the same spelling and capitalization.
• The environment variable was saved successfully.
• The PocketBase instance has finished restarting.
• The hook file is saved and active.

process.env is undefined

PocketBase hooks do not run in Node.js. Use:

$os.getenv("YOUR_KEY")

instead of:

process.env.YOUR_KEY

The hook worked before the variable was changed

Wait a few seconds for the instance restart to finish, then call the endpoint
again. Also confirm that the variable key was not accidentally changed.

You are ready

You can now manage credentials from the PocketBase Cloud dashboard and access
them safely from PocketBase JavaScript hooks using $os.getenv().

This keeps secrets out of your source code and makes credential rotation much
easier: update the value in the dashboard, wait for the instance to restart,
and your existing hooks will use the new credential automatically.