How to keep passwords and API keys safe (Secrets)

TeleportHQ keeps passwords, tokens and API keys in Secrets: named values stored with your project instead of inside your design. When you save a data source, TeleportHQ turns the passwords and tokens you typed into Secrets automatically. You can also add Secrets yourself in Project settings → Data & code → Secrets, and link any credential field to one with its plug button.

Before you start#

• Only the project owner can add, change or remove Secrets. Other people who open the Secrets settings see the list without the New secret button.
• You must be signed in. Signed-out visitors read: "Sign in to store API keys, passwords and other values your site needs but never shows."

Add a secret in TeleportHQ#

1. In the TeleportHQ editor, at the bottom of the left sidebar, click the Project settings cog. The Project settings panel opens.
2. Under Data & code, click Secrets ("Values the site needs but never shows."). The Secrets settings open in a drawer beside the panel.

3. Click New secret. A form opens at the top of the list.
4. In Name, type a name, for example WEATHER_API_KEY.
5. In Value, paste the key.
6. Click Save secret. To leave without saving, click Cancel.

The secret appears in the list with its name. To change its value, click the pencil (Edit secret), type the new value and click Update secret. To delete it, click the trash icon (Remove secret). A window asks Remove the secret "WEATHER_API_KEY"? and names what uses it, for example "It is used by Upcoming events (data source). It will stop working until you add the secret again." Click Remove secret to delete it, or Cancel.

Link a credential field to a secret#

Most password, token and key fields in TeleportHQ data sources have a plug button next to them.

1. Open the data source, for example your REST API.
2. Next to the credential field, click the plug button (tooltip Link to project secret). A Secrets picker opens.
3. Click the secret, for example WEATHER_API_KEY.
4. Click Select.

The field now shows the secret's name instead of the value. To stop using it, click the plug button again (tooltip Unlink from project secret).

How TeleportHQ creates secrets for you#

When you type a password or token straight into a data source and save it, TeleportHQ:

1. creates a secret for each credential, named like DATA_SOURCE_<DATA SOURCE NAME>_<FIELD>, for example DATA_SOURCE_UPCOMING_EVENTS_TOKEN;
2. replaces the field with a link to that secret.

This happens for database passwords, connection strings, SSL certificates and service keys, for Airtable and Turso tokens, and for the Authorization tab of a REST API. Values typed in REST API Headers stay as they are, so put keys in Authorization or link them to a secret.

Check that it worked#

Open Project settings → Data & code → Secrets. Your secret is listed by name. In the data source, the credential field shows the secret's name.

Troubleshooting#

"Secret name must start with a letter or number" Remove symbols or spaces from the start of the name, for example use STRIPE_KEY instead of _STRIPE_KEY.

"This secret name is reserved by the system and cannot be used" TeleportHQ uses that name itself (for example TELEPORT_DB_CONNECTION_STRING). Choose another name.

My data source stopped connecting after I unlinked a secret Unlinking sets the field to the text CHANGE_ME. Type the real value again, or link the field to a secret.

My data source stopped connecting after I removed a secret The data source still points to the removed name. Add a secret with the same name again, or link the field to another secret.

I can't see the New secret button Only the project owner can manage Secrets. Ask the owner to add the secret.

My copied project can't connect to its data sources A duplicate or clone starts without secrets. Open the Issues chip at the top left of the editor and fill in each missing value, or add the secrets with the same names in Project settings → Data & code → Secrets.

Good to know#

• Values are hidden. After the editor reloads, the Secrets list and the picker show each value as ********. The real values stay on TeleportHQ's servers. The sender email address and sender name of an email provider are the exception: they show as typed, because every email shows them anyway.
• Secrets are used across the project: by data sources and the headless CMS, by workflows, by payment providers, and by email and AI providers. The Secrets settings say "Used by CMS integrations and AI providers."
• Secrets are never copied with a project. When you duplicate a project, or someone clones it through a Can clone link, the new project gets no secrets: provider keys, sign-in (OAuth) clients and signing secrets stay with the original's owner. The copy still points to the same secret names, so its Issues chip (top left of the editor) lists each data source and integration whose secret is missing. Type the values there, or add secrets with the same names in Project settings → Data & code → Secrets. Payment provider set-ups and the forms' reCAPTCHA keys aren't copied either. See How to make a project private, view-only or cloneable.
• Spaces in names become underscores, and if a name already exists, a number is added to the end.
• On your published site, TeleportHQ adds the secret values on its server when it publishes, so they aren't written into your pages.
• Downloaded code doesn't hold the values. The code reads each secret by its name from your host's environment variables (settings your hosting keeps outside the code), and the download leaves the values out. Add them yourself where you host the code.