---
title: "Secrets · intentic sandbox API"
description: "Stored values the agent can use without ever reading them. Every route in the secrets group of the intentic sandbox API, with its input, its answer and a playground."
url: "https://intentic.dev/api/secrets/"
---

Connected systems

# Secrets

Stored values the agent can use without ever reading them

**On this page (5 sections)**

- [Store a secret](#secrets-set)
- [Names of the stored secrets](#secrets-list)
- [Delete a secret](#secrets-remove)
- [Every secret this sandbox holds, from everywhere](#secrets-inventory)
- [Show one secret's value](#secrets-reveal)

Write a secret, list which names exist, delete one. Revealing a value is the deliberate exception and the only route that hands one back; everywhere else the daemon substitutes a secret by reference at the moment a command runs.

**POST`/secrets` Store a secret**

Writes one name and value into the sandbox's own store, where running processes pick it up without a restart. Refused until the sandbox has somewhere to keep them.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `key` required The name to store it under,… | string | body |
| `value` required The value | string | body |

### What comes back

| Field | Type |
| --- | --- |
| `ok` Always true | true |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/secrets" \
 -H "x-intentic-control: $INTENTIC_TOKEN" \
 -H "content-type: application/json" \
 -d '{"key":"OPENAI_API_KEY","value":"…"}'
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.secrets.set({
 "key": "OPENAI_API_KEY",
 "value": "…"
});
```

**GET`/secrets` Names of the stored secrets**

Which secrets exist here. Names only, never values.

### What you send

Nothing. Call it as it is.

### What comes back

| Field | Type |
| --- | --- |
| `keys` The names that exist here | string[] |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/secrets" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.secrets.list();
```

**DELETE`/secrets/{key}` Delete a secret**

Removes one by name.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `key` required Which secret, by name | string | address |

### What comes back

| Field | Type |
| --- | --- |
| `ok` Always true | true |

Try it answered in this tab

curl

```bash
curl -X DELETE "$SANDBOX/secrets/OPENAI_API_KEY" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.secrets.remove({
 "key": "OPENAI_API_KEY"
});
```

**GET`/secrets/inventory` Every secret this sandbox holds, from everywhere**

One view across all the places secrets live here: what exists, where it came from and whether it is working. Never any values. This one always answers, even before there is a store to write to.

### What you send

Nothing. Call it as it is.

### What comes back

| Field | Type |
| --- | --- |
| `entries` One entry per secret this sandbox… | object[] |
| `key` What identifies it | string |
| `kind` Where it came from: you set… | "env" | "generated" | "capability" | "provider" |
| `label` A friendlier name, for entries that… | string |
| `status` Whether it exists and, for a… | "missing" | "set" | "connected" |
| `requiredBy` What is waiting on it | object[] |
| `resourceId` Which resource | string |
| `type` What kind of resource it is | string |
| `storedAt` Where it actually lives, in words | string |
| `revealable` Whether its value can be shown… | boolean |
| `ci` Whether a copy has been given… | object |
| `synced` Whether the pipeline has it | boolean |
| `pushedAt` When it was last sent there | string |
| `lastUse` The last time an agent actually… | object |
| `at` When, in milliseconds | number |
| `lane` How it was used: a command,… | "shell" | "code" | "browser" |
| `detail` Where it went: the start of… | string |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/secrets/inventory" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.secrets.inventory();
```

**POST`/secrets/reveal` Show one secret's value**

The only call that hands a value back, and it is for the owner alone. Sent as a body rather than in the address, so the name never ends up in a log or a browser's history.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `key` required Which secret, by name | string | body |

### What comes back

| Field | Type |
| --- | --- |
| `value` The value itself | string |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/secrets/reveal" \
 -H "x-intentic-control: $INTENTIC_TOKEN" \
 -H "content-type: application/json" \
 -d '{"key":"OPENAI_API_KEY"}'
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.secrets.reveal({
 "key": "OPENAI_API_KEY"
});
```

More in Connected systems

[Previous ← Capabilities](https://intentic.dev/api/capabilities/)[Next VPN →](https://intentic.dev/api/vpn/)