# Secret

URL: /business/nouns/secret · Id: `noun:secret`

> A Secret is a named credential stored write-only per environment and filled into a call at run time, never read back by a Worker.

A Secret is a named credential stored write-only per environment and filled into a call at run time, never read back by a [Worker](/business/nouns/worker).

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | The name a Function declares, such as `MAPS_KEY`; `list` returns names only. |
| `environment` | `string` | Yes | The environment that holds this value; a Function deploys to `live` only when every declared Secret exists there. |
| `scope` | `string` | Yes | Whether the whole Startup or one Tenant holds it. |
| `rotatedAt` | `datetime` | No | When the value last changed. |

## Object
```json
{
  "$id": "https://api.sb/kilnbakery.com/secrets/secret_1",
  "$type": "Secret",
  "name": "MAPS_KEY",
  "environment": "test",
  "scope": "startup",
  "rotatedAt": "2026-10-22T12:00:00Z"
}
```

## Relationships
- <a id="rel-used-by"></a>A Secret **is used by** many [Functions](/business/nouns/function): a [Function](/business/nouns/function) declares the Secrets it reads; deploying to `live` fails when one is missing there. `usedBy`, inverse [`uses`](/business/nouns/function#rel-uses).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Secret.revoke](/business/nouns/secret/revoke) | Revoke ends a Secret so no call fills it again; the record and its history stay. | [Security Engineer](/agents/engineering/security-engineer) | [`Secret.revoked`](/business/events/Secret.revoked) | One-way (customer): `send`, `do` |
| [Secret.rotate](/business/nouns/secret/rotate) | Rotate replaces a Secret’s value, and calls already running finish on the old one. | [Security Engineer](/agents/engineering/security-engineer) | [`Secret.rotated`](/business/events/Secret.rotated) | Two-way: `try`, `send`, `do` |
| [Secret.store](/business/nouns/secret/store) | Store writes a Secret’s value for one environment; the value is never returned by any Interface. | [Security Engineer](/agents/engineering/security-engineer) | [`Secret.stored`](/business/events/Secret.stored) | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Secret.get](/business/nouns/secret/get) | Returns one Secret by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Secret.list](/business/nouns/secret/list) | Returns Secrets, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |

A Secret is never deleted: it ends by [Secret.revoke](/business/nouns/secret/revoke), and its records stay.

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Secret.get` | Yes | Yes | Yes | Yes |
| `Secret.list` | Yes | Yes | Yes | Yes |
| `Secret.revoke` | Yes | No | No | No |
| `Secret.rotate` | Yes | Yes | No | No |
| `Secret.store` | Yes | Yes | No | No |

## Call it

**Ask**

```text
Store the secret “MAPS_KEY”.
```

**API**

```bash
curl -X POST https://api.sb/shiftnote.app/secrets/store \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"MAPS_KEY","value":"Example value","environment":"test"}'
```

```json
{
  "api": "https://api.sb/shiftnote.app",
  "secret": {
    "$id": "https://api.sb/shiftnote.app/secrets/secret_1",
    "$type": "Secret",
    "name": "MAPS_KEY",
    "environment": "test",
    "scope": "startup"
  },
  "action": {
    "$id": "https://api.sb/shiftnote.app/actions/action_1",
    "operation": "Secret.store",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/shiftnote.app/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const secret = await $.Secret.store({ name: 'MAPS_KEY', value: 'Example value', environment: 'test' })
```

**CLI**

```bash
npx startup-builder do Secret.store --json '{"name":"MAPS_KEY","value":"Example value","environment":"test"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Secret.store({ name: 'MAPS_KEY', value: 'Example value', environment: 'test' })"
  }
}
```

## Example
A delivery app's [Function](/business/nouns/function) declares `MAPS_KEY`. The key is stored once in the test environment and once in live, and the Function deploys to live only after both exist.