Environment Variables

Environment variables let you store sensitive values - API keys, tokens, configuration strings - outside your tool’s code. Instead of hardcoding a secret directly in your handler, you define it once at the workspace level and Rival injects it at runtime. Your code reads it by name, and the value is never exposed in the tool source or visible to marketplace users.

Why use environment variables

If you embed credentials directly in your tool code, they become part of the version snapshot and are visible to anyone with access to your tool’s code. Environment variables solve this by keeping secrets in a separate, access-controlled store that lives at the workspace level, not inside the tool itself.

This also makes rotation easier. When an API key expires or needs to change, you update the value in one place rather than editing and republishing each tool that uses it.

Creating environment variables

Environment variables are managed in Workspace Settings → API. Each variable has a name and a value. The name is what your code will reference; the value is stored securely and not displayed after saving.

To create one, open Workspace Settings, navigate to the API section, and add a new key-value pair. Give it a descriptive name in uppercase with underscores - for example, OPENAI_API_KEY or DATABASE_URL. This is a convention, not a requirement, but it keeps things consistent across your team.

Assigning variables to tools

Creating a variable at the workspace level does not automatically make it available to every tool. You assign variables to specific tools from that tool’s code & version section. This is intentional - it limits exposure. A tool that handles user-facing text processing has no reason to access your payment processor credentials.

To assign a variable, go to your tool’s code & version section and find the environment variables section. Select the variables from your workspace that this tool should be able to read. Once assigned, the variable will be injected into the tool’s runtime environment on every execution.

Reading variables in your tool code

The way you access environment variables depends on which runtime your tool uses.

Python

import os

def cortexone_handler(event, context):
    api_key = os.environ.get("MY_API_KEY")
    if not api_key:
        return {"statusCode": 400, "body": {"error": "API key not configured"}}
    # use api_key ...
    return {"statusCode": 200, "body": {"ok": True}}

Use os.environ.get("KEY_NAME") rather than os.environ["KEY_NAME"] so that missing variables return None instead of raising a KeyError.

JavaScript

function cortexone_handler(event, context) {
  const apiKey = process.env.MY_API_KEY;
  if (!apiKey) {
    return { statusCode: 400, body: { error: "API key not configured" } };
  }
  // use apiKey ...
  return { statusCode: 200, body: { ok: true } };
}

Lua

function cortexone_handler(event, context)
  local api_key = process.env.MY_API_KEY
  if not api_key then
    return {statusCode = 400, body = {error = "API key not configured"}}
  end
  -- use api_key ...
  return {statusCode = 200, body = {ok = true}}
end

Security

Variable values are encrypted at rest and never returned in API responses or displayed in the dashboard after the initial save. Marketplace users who execute your tool cannot see the variables or their values - they interact only with the inputs and outputs you define.

Variables are scoped to the workspace. Members of your organization can see variable names (so they can assign them to tools), but values are not exposed to non-owner roles.