Secrets: keys your site's code needs

#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.

#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

#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.

#Change or remove a secret

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, 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.

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), 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

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.