putty
API ReferenceLedger

Store or replace a secret (write-only)

Stores `value` under `name`, replacing any existing value at the same scope. This is the only request in the API that carries a secret value, and the value is encrypted the moment it arrives: the response returns metadata only, and no route, tool, event, log, or export ever returns a value afterwards. Limits: 100 secrets per user and 8 KB per value, both enforced here. A value that looks like an EVM private key (64 hex characters, with or without `0x`) or a BIP-39 mnemonic (12-24 words) is refused, as are the names `PRIVATE_KEY`, `MNEMONIC`, and `SEED_PHRASE`: apps should use a wallet (Privy, or the user's own signing flow) instead.

PUT
/secrets/{name}

Stores value under name, replacing any existing value at the same scope. This is the only request in the API that carries a secret value, and the value is encrypted the moment it arrives: the response returns metadata only, and no route, tool, event, log, or export ever returns a value afterwards. Limits: 100 secrets per user and 8 KB per value, both enforced here. A value that looks like an EVM private key (64 hex characters, with or without 0x) or a BIP-39 mnemonic (12-24 words) is refused, as are the names PRIVATE_KEY, MNEMONIC, and SEED_PHRASE: apps should use a wallet (Privy, or the user's own signing flow) instead.

Authorization

bearerAuth
AuthorizationBearer <token>

A bearer token. The Account routes accept a Privy access token; the MCP transport accepts an sk- API key issued by POST /account/api-keys.

In: header

Path Parameters

name*string

The environment-variable-shaped name of the secret. PRIVATE_KEY, MNEMONIC, and SEED_PHRASE are refused.

Match^[A-Z][A-Z0-9_]{0,63}$

Request Body

application/json

The value to store, and its metadata.

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/secrets/string" \  -H "Content-Type: application/json" \  -d '{    "value": "string"  }'
{  "id": "string",  "name": "string",  "scope": "user",  "projectId": "string",  "description": "string",  "usage": "sandbox",  "status": "string",  "createdAt": "string",  "updatedAt": "string",  "lastUsedAt": "string"}

Delete a secret DELETE

Removes the secret and its value. Pass `?projectId=` to delete the project-scoped secret of that name; without it the user-scoped secret is removed. Answers 404 for a secret that is not the caller's, the same as for one that does not exist.

Which secret a name resolves to in a project GET

Reports which scope a name resolves to inside a project: `project` when a project secret shadows a user one, `user` when only the user-scoped secret exists, `none` when neither does. The `shadowed` flag says whether a user-scoped secret of the same name is present behind a project-scoped winner. Metadata only.