Browse docs+

List Vault Environment Fields

Returns only fields marked for environment-variable export in one vault, with their latest stored encrypted payloads.

GET /api/v1/machine/vault/:vaultId/environment-fields

Use this route when a runtime is building project environment JSON and does not need every field on every vault item. The CLI and Node SDK use this endpoint when available, then decrypt the returned field values locally.

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key

Path Parameters

Parameter	Type	Required	Description
`vaultId`	string	Yes	The unique identifier of the vault

Response

Success (200 OK)

{
  "vaultId": "507f1f77bcf86cd799439011",
  "fields": [
    {
      "id": "507f1f77bcf86cd799439034",
      "name": "Password",
      "type": "PASSWORD",
      "order": 3,
      "fieldInstanceId": "507f1f77bcf86cd799439054",
      "fieldInstanceIds": ["507f1f77bcf86cd799439054"],
      "assetId": null,
      "assetIds": [],
      "isEnvironmentVariable": true,
      "value": "{\"v\":3,\"iv\":\"...\",\"t\":\"...\",\"d\":\"...\"}",
      "vaultId": "507f1f77bcf86cd799439011",
      "vaultItemId": "507f1f77bcf86cd799439021",
      "vaultItemName": "Production Database"
    }
  ],
  "count": 1
}

Response Fields

Field	Type	Description
`vaultId`	string	Vault that owns the returned fields
`fields`	array	Environment-exportable field values
`count`	number	Total number of environment fields returned
`fields[].id`	string	Field ID
`fields[].name`	string	Field label. This metadata is not end-to-end encrypted.
`fields[].type`	string	Field type
`fields[].order`	number	Field display order
`fields[].fieldInstanceId`	string \| null	Latest active field-instance ID used for `value`
`fields[].fieldInstanceIds`	string[]	Full active field-instance set for the field
`fields[].assetId`	string \| null	Latest active attached asset ID
`fields[].assetIds`	string[]	Full active asset set for the field
`fields[].isEnvironmentVariable`	boolean \| null	Environment-variable export flag
`fields[].value`	string \| null	Field value as stored. In client-encrypted vaults, this is a v3 vault envelope string
`fields[].vaultItemId`	string	Parent vault item ID
`fields[].vaultItemName`	string	Parent vault item name. This metadata is not end-to-end encrypted.

Audit and Activity

This endpoint records access in two places:

security audit logs use VAULT_FIELD_ACCESSED with environmentOnly: true
vault activity records use ENVIRONMENT_FIELD_READ once for each parent vault item whose environment fields were returned

For AGENT-scoped sessions, the vault activity is attributed to the agent.

Verification Notes

This endpoint never returns already-decrypted environment variables.
The SDK and CLI fetch wrapped vault keys and signer directories separately, unwrap the vault DEK locally, and decrypt each returned value on the runtime host.
Use GET /api/v1/machine/vault/:vaultId/items/:itemId if you need the full signed detail checkpoint for an item.
Use GET /api/v1/machine/vault/:vaultId/fields/:fieldId if you already know a single field ID and need only that one value.

Error Responses

404 Not Found - Vault not found or not accessible

{
  "error": {
    "code": "vault_not_found",
    "message": "The vault with ID \"507f1f77bcf86cd799439011\" was not found or you do not have access to it."
  }
}

Example Request

curl -X GET "https://r4.dev/api/v1/machine/vault/507f1f77bcf86cd799439011/environment-fields" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz"

Use Cases

Project env export: Build environment JSON without fetching full item details.
Agent runtime boot: Load only fields explicitly marked for environment-variable export.
Least data movement: Avoid retrieving sibling fields that the runtime does not need.