eCG Cloud: data and actions
Store keys and secrets safely
Secrets hold the keys your app needs, such as payment or email keys. Learn how to add one, why VITE_ keys are public, and which keys stay private.
A secret is a key or password your app needs to talk to another service, for example a payment provider, an email provider or a map service. Secrets let you keep these values out of your pages and out of your chat.
The most important rule on this page is short. A key that starts with VITE_ is public: anyone who visits your site can read it. A key without that prefix stays on the server and can only be used inside eCG Actions.
Where to find Secrets
- Open your project in the editor.
- Open More actions, then Project settings.
- In the left menu, under eCG Cloud, select Secrets.
The Overview page under eCG Cloud also shows how many secrets the app holds, for example "2 secrets".
You can also ask the agent to save a secret for you. It does not repeat the value back in the chat.
Public and private keys
Your app has two sides. The browser side is what visitors download, so anything placed there can be read by anyone who looks. The server side is eCG Actions, which visitors cannot look into.
| Key name | Who can use it | Use it for |
|---|---|---|
Starts with VITE_, for example VITE_MAPS_KEY |
Your pages, which means every visitor can read it. Your eCG Actions can use it too. | Public values only, such as a publishable payment key or a map key that is limited to your site |
No prefix, for example PAYMENT_SECRET_KEY |
Only your eCG Actions | Anything private: secret payment keys, email keys, passwords, access tokens |
As a safety net, eComGear refuses a VITE_ key when the rest of its name contains SECRET, PRIVATE, TOKEN or SERVICE_ROLE. The message says the key "looks server-only; VITE_ ships to the browser." Save it again without the prefix. This check only looks at the name, so it cannot protect you from a wrongly named key such as VITE_PAYMENT_KEY that holds a private value. You decide what is public.
If your page needs a value in the browser and the value is private, do not put it in a VITE_ key. Ask the agent to create an eCG Action that uses the private key on the server and gives your page only the result.
Add a secret
- Select Add Secret.
- In Key name, type the name, for example
PAYMENT_KEYorVITE_MAPS_KEY. Use capital letters, digits and underscores only. Small letters turn into capitals, and any other character is removed as you type. - Read the hint under the box. It changes as you type:
- With
VITE_, it says the key is available to your app's pages and to eCG Actions, and that you should only save public values. - Without
VITE_, it says the key will not be visible to your pages and can only be used inside eCG Actions.
- With
- In Value, paste the key. It is hidden as you type. Select the eye icon to show it for a moment.
- Select Save.
You see: Secret "NAME" saved and synced to preview and eCG Actions. The new key is available to the live preview and to your actions straight away.
Select Cancel to close the form without saving.
Name rules
| Rule | Example |
|---|---|
| Capital letters, digits and underscores only | MAIL_API_KEY |
| It cannot start with a digit | KEY_2 works, 2_KEY does not |
| The name must be new | You see: Secret "MAIL_API_KEY" already exists. |
| The value cannot be empty | The Save button stays off until you type one |
If the name does not follow the rule, you see: "Key must be uppercase letters, digits, and underscores only."
Names you cannot use
Five names are managed by eComGear and cannot be replaced: VITE_DB_API_URL, VITE_DB_ANON_KEY, VITE_DB_SCHEMA, VITE_FUNCTIONS_API_URL and VITE_REALTIME_URL. They connect your pages to eCG Data and eCG Actions, and they appear in your list once eCG Data is on. If you try to save one you see: "is platform-managed and cannot be overridden."
Read your list
Each secret shows its name and a masked preview that ends with the last four characters of the value, for example ****a1b2. A short value shows only ****. The full value is never shown again after you save it. Not even you can read it back.
Change or remove a secret
You cannot edit a secret in place.
- To change a value, delete the secret, then add it again with the same name and the new value.
- To delete, select the trash icon at the right of its row. You see: Secret "NAME" deleted. There is no extra confirmation, so check the name first.
Deleting a secret also removes it from your actions. An action that depends on it fails the next time it runs, until you add the secret back. Check Recent runs in eCG Actions after a change.
How your app reads a secret
You do not have to write any code. The agent does it for you, and refers to each secret by its name:
- A
VITE_key is read by your pages through the app's environment, for exampleimport.meta.env.VITE_MAPS_KEY. - A key with no prefix is read inside an action as
secrets.NAME.
Tell the agent the secret's name and what it is for, for example: "Use my saved MAIL_API_KEY to send order emails." The agent can see what names you saved before it asks you for something twice.
Good habits
- Use one key per service, and give it only the rights the app needs.
- Put test keys in while you build, then replace them with live keys when you are ready to take real customers.
- Prefer adding private keys here, in Secrets, rather than typing them into the chat.
- Make a note of where each key came from, so you can replace it later.
If you change a VITE_ value after you published, publish again so the public site uses the new value. See Publish your website.
Related pages