Secrets - Telnyx

Secrets are key-value pairs for sensitive data — API keys, database passwords, signing keys. They are scoped to your organization, stored server-side, and never displayed by the CLI after you set them. Every function receives them; there are two ways to read one.

Managing secrets

The secrets commands take positional arguments:

# Add a secret — or update it, same command
telnyx-edge secrets add STRIPE_API_KEY "sk_live_abc123"
# ✓ Secret 'STRIPE_API_KEY' added successfully

# List secret keys (values are never shown)
telnyx-edge secrets list
# SECRET ID                              SECRET NAME         CREATED AT            UPDATED AT
# ------------                           ----------------    -----------------     -----------------
# 1f4cafea-21ce-4e2b-9740-17d971c3d892   DATABASE_PASSWORD   Jun 12, 2026, 09:41   Jun 12, 2026, 09:41
# 21ef7449-edbb-4248-b869-3d1352563a64   STRIPE_API_KEY      May 28, 2026, 16:20   May 28, 2026, 16:20
# a209b1b3-062c-46f6-a2f2-3b0061751190   JWT_SECRET          May 28, 2026, 16:19   May 28, 2026, 16:19

# Delete a secret
telnyx-edge secrets delete OLD_API_KEY
# ✓ Secret 'OLD_API_KEY' deleted successfully

Secrets are injected into function containers at deploy time — after adding or updating one, telnyx-edge ship each function that uses it.

Reading secrets

As environment variables — every language

Each secret is injected into all functions in your organization as an environment variable named after its key. No declaration needed:

TypeScript / JavaScript
Python
Go
Quarkus (Java)

const stripeKey = process.env.STRIPE_API_KEY;
if (!stripeKey) throw new Error("STRIPE_API_KEY not configured");

import os

stripe_key = os.environ["STRIPE_API_KEY"]

stripeKey := os.Getenv("STRIPE_API_KEY")
if stripeKey == "" {
    log.Fatal("STRIPE_API_KEY not configured")
}

String stripeKey = System.getenv("STRIPE_API_KEY");

Through the typed binding — TypeScript

TypeScript projects can additionally declare a [[secrets]] binding in func.toml and read the secret through env.SECRETS:

# func.toml
[[secrets]]
binding = "STRIPE_KEY"       # the handle your code uses
name    = "STRIPE_API_KEY"   # the key stored with `secrets add`

telnyx-edge types   # regenerates telnyx-env.d.ts from the manifest

import { env } from "@telnyx/edge-runtime";

const stripeKey = await env.SECRETS.get("STRIPE_KEY"); // get returns Promise<string>

Both surfaces read the same store. The binding adds two things: env.SECRETS.get accepts only the literal union of declared handles — a typo’d handle fails to compile — and the in-code handle is decoupled from the stored key name, so you can swap name in the manifest without touching code. The binding SDK is TypeScript-only today; other runtimes use the injected environment variables. Enforced when [[secrets]] is declared: a binding named SECRETS and duplicate [[secrets]] handles are hard errors — ship fails. An [env_vars] entry named SECRETS only warns (it shadows the env.SECRETS namespace), so rename it. See Bindings for how the env namespace works.

Rotating a secret

add with an existing key overwrites its value:

telnyx-edge secrets add DATABASE_PASSWORD "new-password"
telnyx-edge ship                # redeploy each function that uses it
curl https://my-func-myorg.telnyxcompute.com/health   # verify

Scoping and local development

Secrets are organization-scoped. There is no per-environment scoping (dev/staging/prod) today — if you need separation, encode it in the key name (DEV_DATABASE_PASSWORD, PROD_DATABASE_PASSWORD) and pick one in code. There is no local secrets emulation in the CLI. When running a function locally, export the same names as ordinary environment variables:

STRIPE_API_KEY="sk_test_..." node index.js

Troubleshooting

Symptom	Fix
Variable missing in the function	`telnyx-edge secrets list` to confirm the key exists, then `telnyx-edge ship` — values are injected at deploy time.
Stale value	`secrets add` again, then `ship`.
`env.SECRETS.get` doesn’t type-check	Re-run `telnyx-edge types` after editing `[[secrets]]`; pass the `binding` handle, not the `name`.
CLI rejects the command	`telnyx-edge auth status`, then `telnyx-edge auth login` if needed.

Next Steps

Environment variables — the full picture of what lands in your container’s environment
Bindings — the declare → types → env pattern all bindings share
Configuration — [[secrets]] and every other manifest key

​Managing secrets

​Reading secrets

​As environment variables — every language

​Through the typed binding — TypeScript

​Rotating a secret

​Scoping and local development

​Troubleshooting

​Next Steps