--- title: "Secrets: keys your site's code needs | Briks" url: https://briks.dev/docs/secrets description: "Keep API keys and passwords your site's code needs on the site's server, never in pages or downloads. Add, change and remove them, and the rules Briks enforces." last_updated: 2026-10-08 --- # Secrets: keys your site's code needs Some features need a key, token or password for another service. Secrets is where you keep those values, so your site's code can use them without the value ever showing in a page, a file or the studio. This page covers adding, changing and removing them, and the rules Briks holds them to. 8 minute read Checked against the studio on 8 October 2026 ## What a secret is A secret is a value with a name. The value is usually an API key: the password one program uses to talk to another, such as the key a mailing service gives you. The name is how your site's code asks for it, for example `MAILING_LIST_KEY`. The part of your site that reads secrets runs on the server, behind its routes (addresses under `/api/` that run code rather than show a page). The value stays there. It isn't in the site's pages, it isn't sent to visitors' browsers, and it isn't in the code you can download. Once saved, a value can never be shown again, by anyone, you included. The studio keeps only the name, who saved it and when. Keep your own copy somewhere safe, such as a password manager. You only need secrets when your site's own code works with something that needs a key. A brochure site with a contact form needs none. Where 1. Projects 2. Your project 3. Settings 4. Secrets ## Before you start - **Publish the site once.** Secrets are kept only on the published site, never by the studio. Until the first publish the page says **Publish the site first** and nothing can be added. - **Check your role.** Editors, Admins and Owners add, change and delete secrets. Viewers see the names and when each was saved. - **Pick a name.** Letters, digits and underscores, starting with a letter, up to 128 characters. Capitals with underscores is the usual style. Names starting with `BRIKS_` are kept for the studio. - **Mind the limits.** A value can be up to 5 KB, enough for any key or certificate. A project holds up to 100 secrets, the studio's own included. ## Add a secret 1. Press Add secret Where: Settings, Secrets With no secrets yet, the button sits in the middle of the page. Once you have some, it is beside the search box above the list. 2. Type the name Where: Add a secret Enter it in **Name**, exactly as the feature will ask for it. Names are case sensitive, so `MAILING_LIST_KEY` and `Mailing_List_Key` are different secrets. 3. Paste the value Where: Add a secret Paste the key into **Value**. The dialog reminds you: Once saved, the value is never shown again. Keep your own copy if you need one. 4. Save it Where: Add a secret Press **Add secret**. You see, for example: MAILING\_LIST\_KEY was added. The live site has it now. ## Import several from a .env file A .env file is a plain text file of `NAME=value` lines, one per secret. Developers often keep one. If you have one, you can bring every line in at once. 1. Press Import .env Where: Settings, Secrets The **Import a .env file** dialog opens. 2. Give it the lines Where: Import a .env file Paste the lines into the box, drop the file onto it, or press **Choose a file**. A file can be up to 256 KB. 3. Check the preview Where: Import a .env file Each name is tagged **New**, or **Replaces** when a secret with that name exists and will take the new value. Lines that can't be used are listed as skipped, each with the reason. 4. Import Where: Import a .env file Press the import button, which counts what it will save, such as **Import 3 secrets**. Nothing is saved before you do. ## Change or remove a secret 1. Give it a new value Where: Settings, Secrets Open the three dots on its row and choose **Edit value**. The dialog says: The new value replaces the old one, which is never shown. Paste the new value and press **Save value**. 2. Or delete it Where: Settings, Secrets Choose **Delete** instead. The dialog warns: Code on the site that reads it stops finding it. This cannot be undone. Press **Delete** to confirm. Changes reach the live site at once: you see The live site has it now, or for a delete, The live site no longer has it. With many secrets, the **Search secrets** box finds one by name. The table shows each one's **Name** and **Last saved**, with who saved it. Some rows carry a **Managed** tag. The studio sets these for its own services, such as the site's emails, and they can't be changed or deleted here. ## How the build uses a secret Your site's code reads a secret by its name each time it runs, so a build never needs the value. When you ask the studio to connect your site to another service, such as a mailing list or an AI model, its code reads that service's key by a clear name, such as `MAILING_LIST_KEY`. You add the value here, under that name. ## Being asked for a key before a build - **A change to a published site.** When your request connects another service, the status reads **Checking which keys this needs** for a moment. If the site has no value for a key yet, the studio asks before building. The card in the conversation has a field for each key, up to 3 for one change. Paste the value and press **Save and build**: it goes straight to the site's Secrets, never into the conversation, and the change starts. Press **Add it later** to build without it. - **A message sent while it waits** joins the change. Keys you already saved or chose to add later are never asked again: if your new message connects another service, only its key is asked, once the first card is done. - **A new site.** Secrets need a published site, so a first build can't take a key yet. Among its questions before building, it can ask whether to build the connection now and add the key once the site is live, or leave that part out for now. - In [Telegram](https://briks.dev/docs/telegram), the card has a button for each key that opens Secrets in the studio, and **Build** to carry on. A key is never sent through a chat. ## Needed by the site After every publish, Briks reads which secret names the site's own code asks for. Those with no value yet are listed first on this page, tagged **Needed by the site**. Press **Add value** on one and the form opens with its name filled in. Until a name has a value, the part of the site that uses it doesn't work. The reply to a build or change names them too, for example: The site reads MAILING\_LIST\_KEY, which has no value yet: add it in Project Settings โ†’ Secrets. Each name has its own button, such as **Add MAILING\_LIST\_KEY**, that opens this page with the name filled in. The same sentence comes in the notification, and in Telegram when it tells you a build finished. ## A key pasted into a message Briks recognises the usual shapes of service keys and tokens. A key pasted into the studio chat, a new project's description, a project's brief, a message to an agent or its instructions, the Visual Editor's Ask AI or a chat with the bot is taken out before the message is kept or read, and replaced with `[key removed: add it in Settings โ†’ Secrets]`. The studio says so at once: A key was removed from your message so it isn't stored. Add it in Project Settings โ†’ Secrets. The reply has an **Open Secrets** button to this page. In the thread of an agent that works on every project, **Open Secrets** lists your projects so you can pick the one the key is for. Something an agent should remember is refused if it holds a key. Never paste a key into the chat A key of a shape Briks doesn't recognise stays in the message, and everything you type in the studio chat is kept in the project's conversation. Save keys under **Secrets** and refer to them by name only. The same goes for the File Explorer: don't type a key into a file. Before a site publishes, Briks reads its own code for keys written into files: values that look like keys by their shape, and values given to anything named like a key, token or password. If it finds one, the build is sent back to take the value out and read the secret by name instead. ## Security rules Briks enforces - Values go straight to the published site's server side, encrypted. The studio never keeps them, never shows them again and never writes them to its logs. - Values never appear in the site's pages, in visitors' browsers or in the code you download. - Only Editors, Admins and Owners can add, change or delete secrets. - Names starting with `BRIKS_` belong to the studio, and managed secrets can't be changed. - A project can make up to 60 changes to its secrets a minute. Past that you see: That is a lot of changes at once. Wait a minute and try again. ## When a secret goes missing Secrets belong to the site's address. If you change the address (see [Your site's address](https://briks.dev/docs/site-address)), your secrets stay with the old one. The studio's message lists them and asks you to enter them again under **Settings**, **Secrets**, and each row shows **Not on the site ยท enter again**. Choose **Edit value** on each one and paste its value. If the site's code asks for a secret that isn't there, that part of the site answers: Part of this site is not set up yet. Check the name matches exactly, capitals included, and that the row doesn't say **Not on the site**. ## Worked example: replacing a leaked key What happened A florist in Cork > Their mailing service warned that the key saved as `MAILING_LIST_KEY` had turned up in an old email thread. They made a new key at the mailing service, opened **Settings**, **Secrets**, chose **Edit value** on `MAILING_LIST_KEY`, pasted the new key and pressed **Save value**. MAILING\_LIST\_KEY has its new value. The live site has it now. Only then did they delete the old key at the mailing service, so the site never had a moment without a working key. Nothing had to be rebuilt, because the code asks for the key by name. ### Can I see a secret's value later? No. Not you, not a teammate, not Briks. Keep your own copy when you save it. ### Does adding a secret change my site by itself? No. A secret does nothing until the site's code reads it by name. Ask the studio for the feature that uses it. ### Are secrets in the code I download? No. The download holds the site's own files, and keys are never written into them. ### Why can't I add one? Either the site hasn't been published yet, or your role is Viewer. The page says which. ## Read next - [Working on a project **Your site's code** Browse, edit and publish your site's code in the File Explorer on every plan. On a paid plan, download any version as a zip, and see what it leaves out.](https://briks.dev/docs/code) - [Publishing and domains **Your site's address** Every Briks site gets an address at briks.live. How the name is chosen, the rules a new name must follow, how to change it and what happens to the old one.](https://briks.dev/docs/site-address) - [Workspaces and account **Members and roles** Invite people by emailed link and give each one a role: Owner, Admin, Editor or Viewer. See what each role can do and how many people each plan holds.](https://briks.dev/docs/members-and-roles) - [Data and automation **Logs** Read the build log and the last day of your site's requests, filter by level or status, and track down a failing form, a failing job or a slow page.](https://briks.dev/docs/logs) Still stuck? Write to [hello@briks.dev](mailto:hello@briks.dev) with your project's name and what you expected to see. A screenshot helps.