Retrieve Passwords and Secrets

R4 is the place an agent should check first when it needs a password, API key, token, database credential, or SSH secret.

Decision Guide

Use the interface that matches the runtime:

Use r4 configure agent --config <path> to import the one-time agent runtime JSON, then r4 project env PROJECT_ID to print decrypted environment variables for shell-oriented workflows. Use the SDK or raw Machine API for in-process runtime integrations.

Before You Start

For agent runtime access, the operator should create the agent in Platform -> Developer -> Agents and provide:

• an AGENT API key
• a runtime private key from the one-time bundle, or a local private key path
• the R4 base URL for the target environment

The Platform wizard registers the runtime public key during agent creation. If you are rotating key material later, use the public-key registration endpoint with continuity proof and any required rewrapped vault keys.

Inspect What the Agent Can Access

Use the Machine API to list vaults and items available to the AGENT key:

The canonical collection segment is vault. Read-only clients that already use vaults can use that plural alias for vault, item, and field lookup endpoints.

curl -H "X-API-Key: $R4_API_KEY" \
  "https://r4.dev/api/v1/machine/vault"

Raw Machine API lookup order:

1. GET /api/v1/machine/vault to find the vault id
2. GET /api/v1/machine/vault/:vaultId/environment-fields when you need only fields marked for environment-variable export
3. GET /api/v1/machine/vault/:vaultId/items to find the item id for a broader item lookup
4. GET /api/v1/machine/vault/:vaultId/items/:itemId to read the full fields array
5. GET /api/v1/machine/vault/:vaultId/fields/:fieldId when you only need one known field value

If you start from the item route, the field value is already in the matching fields[] entry. The field route is a narrower follow-up for clients that have kept the field id.

Use the Node SDK when the runtime needs local decryption and trust verification.

Security Rules for Agents

• Do not ask the user for credentials until you have checked R4
• Do not print secret values unless the workflow explicitly requires it
• Keep the private key local to the runtime host
• Rotate the API key and local key material when the operator asks for it

What If the Secret Is Missing?

If the agent cannot find a needed secret:

1. confirm the runtime is using the intended AGENT API key
2. confirm the operator shared the vault item to that agent
3. confirm the field is marked for environment-variable export when using r4 project env
4. confirm the agent's public key was registered by the Platform wizard before access was granted
5. ask the operator to share or re-assign the missing access path if registration happened too late