# Secrets

> Give By Dawn's agents the API keys, tokens and credentials they need, encrypted so only your own machines can read them.

This page shows you how to give agents a credential, such as a Stripe key or an npm token, without pasting it
into a ticket. By the end you'll have added a secret, chosen which agents can use it, and know how to change
it later.

A **secret** is a named value an agent reads as an environment variable while it works, for example
`STRIPE_API_KEY`. By Dawn encrypts it in your browser before it's saved, for your organization's paired machines
only. So By Dawn's servers store it but can't read it, and nobody can view it again once it's saved, in the app or
anywhere else.

Secrets live in **Settings › Organization › Secrets**. Anyone in the organization can see the
list of names and where each one applies, but never a value. Adding, rotating and deleting secrets needs an
org owner or admin.

## Before you start

- Pair at least one machine with your organization (see [Remote agents and machines](https://docs.bydawn.com/remote-agents/)). A
  secret is encrypted for the machines that will run your agents, so with none paired there's nobody to encrypt
  for and By Dawn won't save it.
- Have the value ready to paste. You type it once and never see it again.

## Add a secret

1. Choose **Add secret**. **Add a secret** opens.

2. Choose a **Scope**, which decides which agents can use it:
   - **Organization**: every project and agent in the organization.
   - **Project**: only agents working on one project's tickets. Choose the **Project**.
   - **User**: only agents running on one member's behalf. Choose the **Member**.

3. Give it a **Name**: the environment variable agents read it as, such as `STRIPE_API_KEY`. Use letters,
   digits and underscores, and don't start with a digit. Names starting with `SAW_` are reserved for By Dawn's own
   settings, so the form refuses them.

4. Paste the **Value**.

5. Choose **Encrypt & save**. Under the value, the drawer says how many machines it's encrypting for.

Each secret then shows its name, the project or member it applies to, and how many recipients can read it.

## Which secret an agent gets

When an agent starts on a ticket, it gets every secret that applies to that ticket: the organization's, the
ticket's project's, and those of the member it runs on behalf of. If two share a name, the most specific one
wins: **user, then project, then organization**. So a project can override an organization-wide `NPM_TOKEN`
by adding its own with the same name, without touching anyone else's.

## Change or remove a secret

Open a secret's menu:

- **Rotate value** replaces the value. The name, scope and project or member stay the same. Choose **Encrypt &
  rotate** to save.
- **Delete** removes the secret. Agents that start afterwards no longer get it.

> **Caution:** A secret is encrypted for the machines paired **when you save it**. A machine you pair later can't read
> existing secrets until you rotate them, so after pairing a new machine, rotate the secrets its agents need.
> Rotating with the same value is fine.

## Secrets in your repos' GitHub Actions

Organization and project secrets can also be pushed into a repo's Actions or Dependabot secrets by a repo
bootstrap policy.
See [Repo bootstrap](https://docs.bydawn.com/repo-bootstrap/#why-secrets-are-pushed-by-an-agent) for how that works and why an agent
does the pushing. A value that isn't secret, such as a region or an environment name, can be an Actions variable
instead: see [Actions variables](https://docs.bydawn.com/actions-variables/).

## FAQ

**Can I see a secret's value after I've saved it?**

No. By Dawn only ever shows a secret's name and where it applies. To change the value, rotate it.

**Why does Add a secret say there are no devices to encrypt for?**

Your organization has no paired machines yet, so nothing could ever read the value. Pair a machine first, then
add the secret.

**An agent says a secret is missing. What should I check?**

Check that the secret's scope covers the ticket's project, or the member the agent runs for. If it does, the
machine running the agent was probably paired after the secret was saved: rotate the secret so that machine can
read it.

**What does Secrets aren't available in this app mean?**

The app you're using isn't connected to the service that lists your organization's machines, so it has
nothing to encrypt for. Open **Settings › Organization › Secrets** while you're signed in to your
By Dawn organization.

## Where to go next

- [Remote agents and machines](https://docs.bydawn.com/remote-agents/): pair the machines your agents run on.
- [Skills & Tools](https://docs.bydawn.com/skills-and-tools/): shared tools often read their credentials from secrets.

Source: https://docs.bydawn.com/secrets/