putty
API ReferenceLedger

Which secret a name resolves to in a project

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.

GET
/secrets/{name}/resolved/{projectId}

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.

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}$
projectId*string

The project to scope the request to.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/secrets/string/resolved/string"
{  "name": "string",  "scope": "user",  "shadowed": true,  "secret": {    "id": "string",    "name": "string",    "scope": "user",    "projectId": "string",    "description": "string",    "usage": "sandbox",    "status": "string",    "createdAt": "string",    "updatedAt": "string",    "lastUsedAt": "string"  }}

Store or replace a secret (write-only) PUT

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.

Which projects a secret is usable from GET

Reports the projects a secret is usable from. A user-scoped secret is usable from every one of the caller's projects; a project-scoped secret is usable from exactly its own. Metadata only.