secret

Vault-backed secret storage and rotation.

Amfelt REST API · v1.13.0 · https://api.amfelt.com

POST `/v1/secrets/update`

Update an existing secret.

Overwrites the credential map of an existing secret. The target key is carried in the body so it may contain slashes. An agent may use only the vault refs of the projects pinned to it, and may write only a ref <environment>/database/<project id>/<name> of such a project. Any other key is refused with 403, code permission_denied, and a message naming the rule, never the ref. The operator-bootstrap token is not scoped by this rule and stays organization-wide.

Request body (required)

application/json

Property	Type	Required	Description
`fields`	object	Yes	The new credential map; replaces stored values.
The new credential map; replaces stored values.
`key`	string	Yes	The vault key of the secret to update; may contain slashes. Examples: `myapp/prod/api_key`.
The vault key of the secret to update; may contain slashes. Examples: `myapp/prod/api_key`.

Responses

200 The secret was updated.

application/json

Property	Type	Required	Description
`key`	string	Yes	The vault key of the secret.
The vault key of the secret.
`version`	integer	Yes	Current version of the secret.
Current version of the secret.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/secrets/resolve`

Resolve a secret.

Returns the stored payload for the given vault reference. The policy engine gates each resolve; a deny surfaces as 403. An agent may also use only the vault refs of the projects pinned to it: a ref <environment>/database/<project id>/<name> of such a project, and the source and target refs the control plane recorded for those projects. Any other ref is refused with 403. Both refusals carry code permission_denied, and a message that never names the ref. The operator-bootstrap token is not scoped by the pinned projects and stays organization-wide.

Request body (required)

application/json

Property	Type	Required	Description
`purpose`	string	No	Optional opaque audit label.
Optional opaque audit label.
`ref`	string	Yes	The vault reference of the secret to resolve. Examples: `production/llm/anthropic`.
The vault reference of the secret to resolve. Examples: `production/llm/anthropic`.

Responses

200 The resolved secret payload.

application/json

Property	Type	Required	Description
`classification`	SecretClassification	Yes

`fields`	object	Yes	The typed credential map.
The typed credential map.
`type`	SecretType	Yes

`version`	integer	Yes	Current version of the secret.
Current version of the secret.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/secrets/cache/invalidate`

Invalidate a secret's cache entry.

Drops the cached payload for the given vault key so the next resolve fetches a fresh copy from the vault. An agent may use only the vault refs of the projects pinned to it: a ref <environment>/database/<project id>/<name> of such a project, and the source and target refs the control plane recorded for those projects. Any other key is refused with 403, code permission_denied, and a message naming the rule, never the ref. The operator-bootstrap token is not scoped by this rule and stays organization-wide.

Request body (required)

application/json

Property	Type	Required	Description
`key`	string	Yes	The vault key whose cache entry to drop; may contain slashes. Examples: `myapp/prod/api_key`.
The vault key whose cache entry to drop; may contain slashes. Examples: `myapp/prod/api_key`.

Responses

204 The cache entry was invalidated.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/secrets`

Stores a new secret in the caller’s organization vault and returns the server-generated key. Agent-callable. An agent may use only the vault refs of the projects pinned to it, and may write only a ref <environment>/database/<project id>/<name> of such a project. The ref is the body’s environment, type and name joined by slashes, so an agent registers type database under a name <project id>/<name>. Any other ref is refused with 403, code permission_denied, and a message naming the rule, never the ref. The operator-bootstrap token is not scoped by this rule and stays organization-wide.

Request body (required)

application/json

Property	Type	Required	Description
`classification`	SecretClassification	Yes

`environment`	string	Yes	DTAP environment to scope the secret to. Examples: `production`.
DTAP environment to scope the secret to. Examples: `production`.
`fields`	object	Yes	The typed credential map (e.g. host, port, username, password).
The typed credential map (e.g. host, port, username, password).
`name`	string	Yes	Human-readable name of the secret.
Human-readable name of the secret.
`rotation_policy`	RotationPolicy	No

`type`	SecretType	Yes

Responses

201 The secret was registered.

application/json

Property	Type	Required	Description
`key`	string	Yes	The vault key of the secret.
The vault key of the secret.
`version`	integer	Yes	Current version of the secret.
Current version of the secret.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/secrets/schema/{category}`

Get the schema for a secret category.

Returns the field shape for the given secret category. Tenant-agnostic platform metadata read from embedded YAML; no auth required.

Parameters

Name	In	Required	Type	Description
`category`	path	Yes	string	The secret category (e.g. database, api-key, s3).
The secret category (e.g. database, api-key, s3).

Responses

200 The base schema for the category.

application/json

Property	Type	Required	Description
`fields`	SecretFieldSchema []	Yes	The field shape for this category (optionally driver-extended).
The field shape for this category (optionally driver-extended).
`type`	string	Yes	The secret category this schema describes. Examples: `database`.
The secret category this schema describes. Examples: `database`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

GET `/v1/secrets/schema/{category}/{driver}`

Get the schema for a secret category merged with a driver extension.

Returns the base schema merged with any driver-specific extension. Tenant-agnostic platform metadata; no auth required.

Parameters

Name	In	Required	Type	Description
`category`	path	Yes	string	The secret category (e.g. database, api-key, s3).
The secret category (e.g. database, api-key, s3).
`driver`	path	Yes	string	The driver name for the merged-schema endpoint (e.g. postgres, mysql).
The driver name for the merged-schema endpoint (e.g. postgres, mysql).

Responses

200 The base schema merged with the driver extension.

application/json

Property	Type	Required	Description
`fields`	SecretFieldSchema []	Yes	The field shape for this category (optionally driver-extended).
The field shape for this category (optionally driver-extended).
`type`	string	Yes	The secret category this schema describes. Examples: `database`.
The secret category this schema describes. Examples: `database`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Schemas

Secret Update

type: SecretUpdate

The payload for POST /v1/secrets/update — updates an existing secret by key.

Property	Type	Required	Description
`fields`	object	Yes	The new credential map; replaces stored values.
The new credential map; replaces stored values.
`key`	string	Yes	The vault key of the secret to update; may contain slashes. Examples: `myapp/prod/api_key`.
The vault key of the secret to update; may contain slashes. Examples: `myapp/prod/api_key`.

Secret Ref

type: SecretRef

A reference to a secret and its current version.

Property	Type	Required	Description
`key`	string	Yes	The vault key of the secret.
The vault key of the secret.
`version`	integer	Yes	Current version of the secret.
Current version of the secret.

Error

type: Error

The standard error envelope returned by every non-2xx response.

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Secret Resolve

type: SecretResolve

The payload for POST /v1/secrets/resolve.

Property	Type	Required	Description
`purpose`	string	No	Optional opaque audit label.
Optional opaque audit label.
`ref`	string	Yes	The vault reference of the secret to resolve. Examples: `production/llm/anthropic`.
The vault reference of the secret to resolve. Examples: `production/llm/anthropic`.

Secret

type: Secret

A resolved secret payload returned by POST /v1/secrets/resolve.

Property	Type	Required	Description
`classification`	SecretClassification	Yes

`fields`	object	Yes	The typed credential map.
The typed credential map.
`type`	SecretType	Yes

`version`	integer	Yes	Current version of the secret.
Current version of the secret.

Secret Classification

type: SecretClassification

BIO2 sensitivity classification of a secret.

Secret Type

type: SecretType

Category of a secret.

Cache Invalidation

type: CacheInvalidation

The payload for POST /v1/secrets/cache/invalidate.

Property	Type	Required	Description
`key`	string	Yes	The vault key whose cache entry to drop; may contain slashes. Examples: `myapp/prod/api_key`.
The vault key whose cache entry to drop; may contain slashes. Examples: `myapp/prod/api_key`.

Secret Registration

type: SecretRegistration

The payload for POST /v1/secrets — registers a new secret.

Property	Type	Required	Description
`classification`	SecretClassification	Yes

`environment`	string	Yes	DTAP environment to scope the secret to. Examples: `production`.
DTAP environment to scope the secret to. Examples: `production`.
`fields`	object	Yes	The typed credential map (e.g. host, port, username, password).
The typed credential map (e.g. host, port, username, password).
`name`	string	Yes	Human-readable name of the secret.
Human-readable name of the secret.
`rotation_policy`	RotationPolicy	No

`type`	SecretType	Yes

Rotation Policy

type: RotationPolicy

Controls automatic credential rotation.

Property	Type	Required	Description
`expiry_alert_days`	integer	Yes	Days before expiry to start alerting.
Days before expiry to start alerting.
`interval_days`	integer	Yes	Days between automatic rotations.
Days between automatic rotations.

Secret Schema

type: SecretSchema

The schema for a secret category, optionally merged with a driver extension.

Property	Type	Required	Description
`fields`	SecretFieldSchema []	Yes	The field shape for this category (optionally driver-extended).
The field shape for this category (optionally driver-extended).
`type`	string	Yes	The secret category this schema describes. Examples: `database`.
The secret category this schema describes. Examples: `database`.

Secret Field Schema

type: SecretFieldSchema

A single field within a secret category schema.

Property	Type	Required	Description
`classification`	SecretClassification	No

`description`	string	No	Human-readable description of the field.
Human-readable description of the field.
`format`	string	No	UI hint for form rendering. Valid values are: `text`, `multiline`, `json`, `password`.
UI hint for form rendering. Valid values are: `text`, `multiline`, `json`, `password`.
`label`	string	No	Human-readable display name for form rendering. Prefer this over a name-derived guess or the description.
Human-readable display name for form rendering. Prefer this over a name-derived guess or the description.
`name`	string	Yes	Field name as it appears in the credential map.
Field name as it appears in the credential map.
`required`	boolean	Yes	Whether the field is required to register a secret of this category.
Whether the field is required to register a secret of this category.
`values`	string[]	No	Allowed values for enum-style fields.
Allowed values for enum-style fields.

Last updated on October 31, 2026

Docs

secret

POST `/v1/secrets/update`

Request body (required)

Responses

Security

POST `/v1/secrets/resolve`

Request body (required)

Responses

Security

POST `/v1/secrets/cache/invalidate`

Request body (required)

Responses

Security

POST `/v1/secrets`

Request body (required)

Responses

Security

GET `/v1/secrets/schema/{category}`

Parameters

Responses

GET `/v1/secrets/schema/{category}/{driver}`

Parameters

Responses

Schemas

Secret Update

Secret Ref

Error

Secret Resolve

Secret

Secret Classification

Secret Type

Cache Invalidation

Secret Registration

Rotation Policy

Secret Schema

Secret Field Schema

On this page

Docs

secret

POST /v1/secrets/update

Request body (required)

Responses

Security

POST /v1/secrets/resolve

Request body (required)

Responses

Security

POST /v1/secrets/cache/invalidate

Request body (required)

Responses

Security

POST /v1/secrets

Request body (required)

Responses

Security

GET /v1/secrets/schema/{category}

Parameters

Responses

GET /v1/secrets/schema/{category}/{driver}

Parameters

Responses

Schemas

Secret Update

Secret Ref

Error

Secret Resolve

Secret

Secret Classification

Secret Type

Cache Invalidation

Secret Registration

Rotation Policy

Secret Schema

Secret Field Schema

On this page

POST `/v1/secrets/update`

POST `/v1/secrets/resolve`

POST `/v1/secrets/cache/invalidate`

POST `/v1/secrets`

GET `/v1/secrets/schema/{category}`

GET `/v1/secrets/schema/{category}/{driver}`