# The Secrets guide

Set up Dbrij Secrets step by step: what you need, what to press, and how you know each step worked.

Canonical page: https://dbrij.com/products/secrets/guide

## Set up Secrets, step by step

By the end your app keys live in a project with a key for each environment, your recovery kit is saved, and the people who need them can open them.

Before you start, have these ready

- The .env file or keys you want to keep here.
- A passphrase you will remember: it opens your key, and Dbrij cannot reset it.
- Somewhere offline to keep a recovery kit.

1. ### Set up your key

  Choose a passphrase. It encrypts your key in your browser, and Dbrij stores only the sealed result. The company vault uses the same one.
  [Open Secrets](https://dbrij.com/secrets/projects)
2. ### Create a project and save the kit

  Name it and pick its environments. Each gets its own key, made in your browser. Save the recovery kit before the project is made: it is the way back if every key holder loses access.
  [New project](https://dbrij.com/secrets/projects)
  You will know it worked when the project opens with its environments.
3. ### Add your secrets

  Add them one by one, or import a .env file and see exactly what will be added and replaced. Review and save: every save is kept as a version.
  [Your projects](https://dbrij.com/secrets/projects)
4. ### Give people access

  In a company project, add colleagues and give each a role in each environment: read, read and change, write without reading, or a role you name yourself. Pick an end date for temporary access.
  [Your projects](https://dbrij.com/secrets/projects)
  You will know it worked when they can open what they were given.
5. ### Give your app its secrets

  In Machines, add one for each server or pipeline and choose what it reads. Copy its token when it is shown, then start your app with dbrij secrets run, or load them with the Node or Python library.
  [Your projects](https://dbrij.com/secrets/projects)
  You will know it worked when your app starts with its secrets and nothing is kept in a file.

## Questions people ask

### Can Dbrij read my secrets?

No. Values are encrypted in your browser and their keys reach Dbrij only wrapped to the people you chose and to your recovery kit. The names of secrets are kept in plain text, so never put a secret in a name.

### I forgot my passphrase. What now?

Another key holder can pass you the keys again after you set up a new key, or someone with the recovery kit can open the project. Dbrij cannot, because it never had the keys.

### Can Dbrij read what my servers receive?

No. A machine token has two halves. Dbrij keeps a fingerprint of the first, which proves the machine, and never sees the second, which opens the values on the machine itself.

### A machine token leaked. What now?

Open the machine in Machines and revoke that token: it stops working within 30 seconds. Make a new one, and replace the values it could read if they matter.

### Someone left the team. What should I do?

Remove them from the project. You see every secret they could read: replace the ones that matter where they are used, then give each environment a new key in Settings.

## How each part works

### [What Secrets is](#what-secrets-is)

Secrets keeps the keys your apps need: database addresses, payment keys, email API keys, and the rest of a .env file.

Each environment, such as Development, Staging and Production, has its own key, so access to one never opens another.

### [Projects, the switch and the company owner](#projects-and-owners)

Everything in Secrets belongs to a project: its secrets, servers, keys and certificates. Pick it with Project at the top of any Secrets page, and every page follows it. All projects shows everything you are in.

- A project’s admins add servers, keys and certificates; its members use them and ask for access.
- The company owner and its admins see every project in the company, even ones they are not in, and can join any of them as an admin in one step.
- Joining gives the servers, keys and certificates at once. The secrets stay sealed until someone who holds the keys passes them on from the project’s People tab. The project’s admins are told.
- Insights lists what needs attention across the projects you look after: keys only one person holds, things about to end, rotations that stopped, leaks found in code and access nobody uses. Each line opens the place to fix it.

### [Machines, the command line and libraries](#machines)

A machine is a server, a CI job or a script that reads secrets without a person. Each gets its own token, reads only the environments you choose, and shows in Activity every time it reads.

- Start any command with its secrets: dbrij secrets run -- npm start. The token stays out of the command.
- Export them as .env, JSON, YAML or a Docker env file, compare with a local .env, or push a file into an environment.
- In GitHub Actions, log in with GitHub instead of storing a token: only the key half is saved as a repository secret.
- On AWS, Google Cloud, Azure or Kubernetes, a machine can log in as the identity its cloud already gave it, so no login secret is stored on it at all.
- From your own code, use the Dbrij Secrets library for Node, Python or Go. Each keeps serving the last good copy if Dbrij cannot be reached for a moment.
- An AI assistant in your editor can call an API with a key it never sees: list on the key the hosts it may go to, and it is sent nowhere else.
- Moving from dotenvx? Push the encrypted file with the command line: it opens it on your machine with your own key, and the key never leaves.
- People can use the command line too, after dbrij login: it asks for your vault passphrase once and remembers it on that device for a few hours.

### [Hosting, rotation and the company vault](#connections)

An environment is sealed: only the people and machines holding its key can open it. For Dbrij to put values into a deploy or replace a key for you, an admin lets Dbrij open that environment, for the reasons they choose, in Settings. Every time Dbrij opens it, the reason is in Activity.

- In Connections, link a Hosting service to an environment. Every deploy gets its values, the service’s own variables still win on a name both set, and a change redeploys it, at most once every two minutes.
- If a deploy with new values fails, the service goes back to the last version that ran and stays there until you send the latest again. The change stays in Secrets for you to fix.
- Move a service’s own variables into Secrets in one step. Its old variables are kept for 30 days and can be put back.
- A secret holding a Send, Ping, Resolve, Finance or Developer API key can rotate on a schedule. The old key keeps working until every reader has the new one and the grace period has passed.
- A Postgres or MySQL database outside Dbrij can have its password rotated too: the rotation switches between two of its users, so the app always has one that works.
- Instead of keeping a database password, lease a user of a Hosting Postgres or MySQL for an hour with dbrij secrets lease and the name an admin gave the database in Connections. It is removed when the lease ends, and every lease is in Activity.
- In the company vault, Use in an app copies a password into Secrets. One unlock opens both.
- When somebody leaves the company, their keys go at once and the admins get a task listing what to replace.

### [Syncs to outside services](#syncs)

A sync keeps one folder of an environment in step with a service outside Dbrij: GitHub Actions, GitLab CI, the hosting and edge platforms you may also deploy on, AWS Secrets Manager and Parameter Store, Google Cloud Secret Manager, Azure Key Vault, Coolify, Supabase, or a .env file on your own server over SSH. Add an integration shows the full list.

- Add the service once, in Integrations: a token you make there, or for GitHub the GitHub you already connected in Dbrij. Choose which projects may use it, so nobody adds the same access twice. Dbrij checks it with the service before saving it, keeps it sealed, and never shows it again.
- An admin lets Dbrij open the environment for syncs in Settings: the values are opened only in the memory of each run, and every opening is in Activity.
- Choose the folder (and the folders inside it), where it goes, and how names look there, for example APP_{key}. Only names that fit are ever touched: anything else in the destination is left alone.
- Before the first run, see exactly what it would create, change and delete. Two folders giving the same name, or a name the service refuses, stop the run before anything is written.
- After every change it runs again once things are quiet for ten seconds. Where a service only reads variables when it deploys, the sync can start a deploy and waits until it is live.
- Every six hours it checks the service against what it delivered. Drift can be overwritten, brought into Dbrij where the service shows values, or left.
- A busy service is tried again at 1, 5 and 30 minutes and 2 hours. A refused token pauses every sync of its integration with one alert; a renamed or deleted target stops its sync. Admins are told by email, and a company channel can follow the project to hear it in Chat.

### [Approvals, requests and reminders](#approvals)

In a company project, protect an environment such as Production in Settings, then choose who approves its changes under Approvals: project admins, people you name, or anyone given a role that may approve.

- A save to a protected environment becomes a request. Its approvers are asked by email and with a card in Chat, see exactly what changes, and the last approval needed applies it as one change.
- Nobody approves their own change unless you allow it. A request nobody approves closes on its own after the days you choose.
- If a secret it changes was saved again in the meantime, nothing applies: whoever proposed it brings it up to date, and its approvals start again.
- In an emergency, a person you named applies it at once with a reason, after confirming it is them. It is marked in History, and every approver and admin is told.
- Anyone in the company can ask for access to an environment, for a few hours or until it is taken away. Approved, it starts at once and ends on its own.
- Approve changes and access from your phone too: in the Dbrij app, open Company, then Secrets approvals. Values never leave the web.
- Ask somebody outside for a value with a link. They paste it, it is sealed in their browser to a key only you hold, and you save it into an environment.
- Give any secret a date to be replaced by, or a reminder every few days. Insights lists what needs attention: old secrets, unused access, idle machines and environments with too few key holders.

### [Templates and imports](#templates)

- A template is a value built from other secrets, like a database address made from its user, password and host. Type ${ in a value to pick the names, then save it as a template.
- It can use a secret in another folder or another environment, and it is filled in where it is read, on your machine. One you cannot read is an error that names it, never an empty value.
- A folder can import other folders, so /api gets everything in /shared without copying it. Its own values win.
- Deleting a secret a template uses warns you first, and names the template.

### [Leaks, decoys and the activity trail](#trouble)

- Run dbrij secrets scan to find secrets written into a folder, its staged changes or its history. It can also put itself in front of every commit, so a secret is caught before it is saved.
- Every push to Dbrij Source is scanned. A repository warns by default; its settings can block the push instead. Secrets found lists what was pushed, never the value.
- Plant a decoy key in an environment under a name an intruder would try. It opens nothing, and the moment anybody uses it the admins are told.
- Download a project’s Activity as CSV or JSON for any dates your plan keeps. On Business, stream it as it happens to an address of your own, signed so you can trust it.

### [History and restoring](#history)

- Every save is kept as a version, with who made it and when.
- Open any change in History and put back what was there before it. The restore is a change too, so it can be undone.
- Each secret has its own list of versions; any one can be put back into the editor.

### [Plans](#plans)

- People are billed; machines, pipelines and servers are free on every plan.
- Free holds 3 people and 3 projects. Team and Business are priced for each person in your projects.
- Every safety feature is on every plan: roles, temporary access, approvals, history, the activity trail and its export, rotation, leases, decoys and share links. Streaming the trail is on Business.
- On Team and Business, key operations and recorded server hours grow with each person. Past the key operations you are told and nothing is refused; past the recorded hours new sessions wait for the next month, and breaking glass always works.
- The company owner is not billed for a project they joined only to look after it.
- A limit only stops something new. Reading values, deploys and syncs already running never stop, and nothing is deleted when a plan gets smaller.
- Choose or change the plan from Plan on the Secrets home, or from Billing.

### [Good to know](#good-to-know)

- Values open only in a tab you unlocked; closing the tab forgets your keys.
- Personal values are yours alone and only used by you, in place of the shared value.
- A share link opens a set number of times, can ask for a password, and its key never reaches a server.
- A machine can be limited to addresses you list, switched off at once, and never changes a protected environment.
- In a company project, a save to a protected environment waits for its approvers, who are asked by email and in Chat.
- A sync keeps only digests of what it delivered, never a value, and touches only the names its template covers.