# Secrets API

> List, set and remove a project's environment values, and choose whether each reaches the running process, the build, or both.

Source: https://docs.fortly.com/api/secrets

Secrets are environment values for a project, encrypted at rest. Values are never returned by the API — only names, scopes and dates. A project reads its environment when it starts, so setting or removing a secret restarts it. For how your code reads them, see [Environment and secrets](https://docs.fortly.com/deploy/environment).

- `GET /projects/{name}/secrets` — Names, scopes and dates — never values
- `POST /projects/{name}/secrets` — Set a secret, replacing one of the same name
- `DELETE /projects/{name}/secrets/{key}` — Remove a secret

## Scopes

Each secret has a scope that says where its value is given:

| `scope` | The running process | The build |
| --- | --- | --- |
| `runtime` (default) | Yes | No |
| `build` | No | Yes |
| `both` | Yes | Yes |

Use `build` for values a framework bakes into its output at build time, such as a public API address. Keys your server uses at run time belong in `runtime`, so a build script never sees them.

## List secrets

- `GET /projects/{name}/secrets` — Names, scopes and dates — never values

The project's secrets, sorted by name.

- `name` (string, required) — Path parameter. The project's `name`.

**curl**

```bash
curl https://api.fortly.com/projects/my-app-ada/secrets \
  -H "Authorization: Bearer $FORTLY_TOKEN"
```

**JavaScript**

```js
const res = await fetch("https://api.fortly.com/projects/my-app-ada/secrets", {
  headers: { Authorization: `Bearer ${process.env.FORTLY_TOKEN}` },
});
const { secrets, storable } = await res.json();
```

```json
{
  "secrets": [
    { "name": "PUBLIC_API_URL", "created_at": 1791820800, "scope": "build" },
    { "name": "STRIPE_SECRET_KEY", "created_at": 1791734400, "scope": "runtime" }
  ],
  "storable": true
}
```

`storable` is `false` when the platform has no encryption key configured; setting a secret then fails with `501` rather than storing the value unencrypted.

## Set a secret

- `POST /projects/{name}/secrets` — Set a secret, replacing one of the same name

Stores a value, replacing any secret of the same name — its scope included — and restarts the project so the next request sees it.

In the path, `{name}` is the project's `name`. The JSON body takes:

- `name` (string, required) — The variable name: 1–64 capital letters, digits and underscores, not starting with a digit, such as `STRIPE_SECRET_KEY`.
- `value` (string, required) — The value. Not empty, and at most 64 KB.
- `scope` (string, optional) — `runtime`, `build` or `both`. Default `runtime`. Any other value is refused rather than defaulted.

Fortly sets some variables itself, and these names are refused: `PORT`, `HOST`, `PATH`, `FORTLY_API`, `FORTLY_TOKEN`, `DATABASE_URL`, `DATABASE_TRANSACTION_URL`, `PGHOST`, `PGPORT`, `PGDATABASE`, `PGUSER`, `PGPASSWORD` and `PGSSLMODE`.

**curl**

```bash
curl -X POST https://api.fortly.com/projects/my-app-ada/secrets \
  -H "Authorization: Bearer $FORTLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"STRIPE_SECRET_KEY","value":"sk_live_...","scope":"runtime"}'
```

**JavaScript**

```js
const res = await fetch("https://api.fortly.com/projects/my-app-ada/secrets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FORTLY_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "STRIPE_SECRET_KEY", value: process.env.STRIPE_SECRET_KEY, scope: "runtime" }),
});
```

Answers `201`:

```json
{ "name": "STRIPE_SECRET_KEY", "scope": "runtime" }
```

| Status | When |
| --- | --- |
| `400` | The name breaks the rules above or is reserved, the value is empty or too long, or the scope is not one of the three. |
| `501` | The platform cannot encrypt secrets right now, so nothing was stored. |

> **Note:**
>
> A build reads its secrets when it runs. A `build` or `both` secret you change takes effect on the next release, not on the one already live.

## Remove a secret

- `DELETE /projects/{name}/secrets/{key}` — Remove a secret

Removes the secret and restarts the project.

- `name` (string, required) — Path parameter. The project's `name`.
- `key` (string, required) — Path parameter. The secret's name.

**curl**

```bash
curl -X DELETE https://api.fortly.com/projects/my-app-ada/secrets/STRIPE_SECRET_KEY \
  -H "Authorization: Bearer $FORTLY_TOKEN"
```

**JavaScript**

```js
await fetch("https://api.fortly.com/projects/my-app-ada/secrets/STRIPE_SECRET_KEY", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.FORTLY_TOKEN}` },
});
```

Answers `204 No Content`, or `404` with `no secret by that name`.