Secrets

An API key gives access to a paid service or to your data: it must never end up in the site’s code, or in a conversation. Highwind keeps these keys in the project’s secrets: encrypted, read only by your app’s server, and never shown to the agent.

When the agent needs a key

When a feature needs a key your project doesn’t have yet (sending emails with Resend, calling OpenAI, taking payments with Stripe…), the agent doesn’t ask for it in the chat. It shows a card below its reply, and the “Asks for the key RESEND_API_KEY” step in the thread.

1. Read the card. It’s titled The agent needs a key (or The agent needs your Resend connection for a connector) and explains in one sentence what the key is for and where to find it.

2. Get the key from the service’s website (for example resend.com → API Keys).

3. Paste it into the masked field (Paste the value here), then click Add. The note Encrypted, never shown to the agent reminds you that the agent will never see the value.

4. For a connector, Highwind tests the key with the service: “Resend key verified: it works.”, or a message if the service refuses it or doesn’t respond.

The agent doesn’t wait for your key to move on: it writes the code that reads it right away, makes it answer a clear error while the key is missing, and tells you in its summary that the feature will work once the key is added. Once you add the key, the feature works in the preview with nothing else to do.

A key already saved in your account?

For a connector, if you’ve already saved a key for that service in your account, the card offers Use a connection from your account: one click, no need to paste the key again. Otherwise, a new key pasted in the card is encrypted and saved in your account, reusable in your other projects.

If you don’t want to provide the key now, click Dismiss: the request goes away, and the feature keeps answering a clear error.

Never put a key in the chat

Never paste an API key into a message to the agent: it would be stored in the conversation. Always use the card, or Project settings → Secrets.

Where your secrets go

• Encrypted in the database, and never sent back by Highwind once saved: to change a value, you replace it.
• Never shown to the agent: it only sees the names of existing secrets (for example RESEND_API_KEY), never their values. The files that hold them in the preview (.env.local, .dev.vars) are hidden from it, as in the Code tab, and aren’t part of the versions or the downloaded code.
• Read only by your app’s server (worker/index.ts), in the preview as well as once published. They never reach your visitors’ browsers.
• Applied right away: a secret added, replaced or deleted takes effect in the preview, and in the published app too, without republishing.

Going further: reading a secret in the server

The server declares its secrets in the Env interface of worker/index.ts, then reads them with env.NAME:

worker/index.ts (excerpt)

export interface Env {
  OPENAI_API_KEY: string;
}

// in a route:
if (!env.OPENAI_API_KEY) return json({ error: "OpenAI key not added yet" }, 503);

A secret is never read in the front-end code (src/): anything written there is visible to any visitor.

Public values

Some values a connector asks for aren’t secret: a Google Analytics measurement ID (G-…), for example, is visible anyway in the code of any site that uses it. These fields are marked public in forms and shown in clear. The agent gets their value and may write it in browser code. All other fields stay secret.

Managing the project’s secrets

Open Project settings (the gear in the editor header), then the Secrets section.

Action	How
See the secrets	The Project secrets list shows their names, when they were updated, and Requested by the agent for those still waiting for a value.
Add a secret yourself	New secret: a name, a value, then Add.
Change a key	Replace, then paste the new value. The old one is never shown again.
Delete a secret	Delete. Routes using it will answer an error until it’s added again.
Key provided by a connection from your account	It shows Via the “…” connection. Unlink removes the link with this project, without deleting the connection from your account.

Rules for a secret’s name:

• uppercase letters, digits and _, starting with a letter (for example RESEND_API_KEY);
• the HIGHWIND_, CF_, CLOUDFLARE_ and VITE_ prefixes are reserved;
• up to 50 secrets per project, and 5 KB per value.

Tip

A key refused by the service? The card says “Resend refused this key”. Check it, then replace it in Project settings → Secrets. For a connector, the Connectors section of the project settings also offers Test the key.

Linking a connection saved in your account

Connector keys can be saved once in your account, then linked to several projects. You can even keep several for the same service (a test key and a production key, for example).

1. Open the Connectors page from Highwind’s sidebar to see and add your connections.

2. In a project, open Project settings → Connectors and click Use next to the connection you want. Or pick it straight from the agent’s card (Use a connection from your account).

3. The project now uses that key. If you replace it in your account, every linked project gets the new one.

See Account connections.

See also

The app serverThe /api routes that read your secrets.

Account connectionsSave a key once, link it to several projects.

ConnectorsThe services your app can call.

SecurityHow Highwind protects your apps and your data.