Machine API Overview

The R4 machine API is the low-level programmatic interface behind the CLI and the Node SDK.

If your goal is to use R4 as a password manager for an agent runtime, start here:

1. R4 for Agents
2. Authentication and Keys
3. Retrieve Passwords
4. CLI or Node SDK

Base URL

https://r4.dev/api/v1/machine

The Supported Agent Flow

For password retrieval, an agent runtime should:

1. be created in the Platform agent wizard with its runtime public key and selected security groups
2. authenticate with an AGENT API key
3. keep the downloaded local PEM-encoded RSA private key
4. list the vaults it can access
5. retrieve the wrapped vault key and signer directory
6. fetch either narrow environment fields or specific item/field payloads
7. verify the returned trust metadata and checkpoints where present
8. decrypt the shared secrets locally

The MCP server, Node SDK, and CLI already implement this flow for agent runtimes. Use the Platform agent wizard to create new agent credentials, then run r4 configure agent --config <path> on the runtime host when you want the CLI and SDK to share the same local profile.

If that brand-new workspace needs prepaid credit, the same AGENT runtime can now create a crypto funding intent and top up the workspace from any wallet that holds USDC on Base. The wallet does not need its own Stripe account.

Recommended Endpoint Order for Password Retrieval

Optional context-discovery endpoint:

Primary retrieval flow:

Re-registering the same public key is safe. Rotating to a different key still requires the current private key and, when wrapped vault access already exists, a full replacement rewrappedVaultKeys batch.

Project Environment JSON

For the common runtime workflow "give me the environment variables for this project", use the CLI or SDK:

r4 project env PROJECT_ID

const r4 = await R4.create({
  profile: 'openclaw-agent',
  projectId: 'PROJECT_ID',
})
 
console.log(JSON.stringify(r4.env))

The returned JSON is assembled locally from fields marked isEnvironmentVariable. The machine API does not expose a plaintext env-var endpoint. Current clients first try the consolidated bundle route GET /project/:id/environment, which returns the project's vaults with their wrapped keys, signer directories, and encrypted environment fields in one response. Where that route is unavailable, clients fall back to GET /vault?projectId=PROJECT_ID plus per-vault wrapped-key, signer-directory, and GET /vault/:vaultId/environment-fields reads (or list-items and item-detail reads on the oldest servers). Either way, decryption happens locally in the runtime.

The same pattern exists for managed licenses: GET /licenses/:licenseInstanceId/environment returns the zero-trust bundle for the vault items linked to a provisioned license. The CLI exposes it as r4 licenses env LICENSE_INSTANCE_ID [command...], and the SDK as R4.create({ licenseInstanceId }). Both bundle routes require machine.vault.secret.read.

Optional project discovery endpoints:

When a machine caller creates projects through POST /project, ORG-scoped keys and tenants with multiple domain bindings should pass domainTenantId explicitly so the project lands under the intended domain tenant.

Prepaid Crypto Funding

The machine API now includes a provider-neutral prepaid crypto top-up flow for workspace credit.

Routes:

• POST /billing/crypto-funding-intents
• GET /billing/crypto-funding-intents
• GET /billing/crypto-funding-intents/:id

What happens:

1. the agent creates a funding intent with the target USD amount
2. R4 returns USDC / Base deposit instructions plus an expiry
3. the agent sends the exact amount from any compatible wallet
4. R4 settles that deposit back into the normal workspace credit ledger

This keeps the agent-facing contract wallet-only and provider-neutral even though the v1 backend adapter uses Stripe deposit mode.

Identity and Context Discovery

When a headless runtime needs to answer "who am I?" first, call:

curl https://r4.dev/api/v1/machine/me -H "X-API-Key: YOUR_MACHINE_KEY"

The response includes:

• the authentication method, either apiKey or accessToken
• the profile type, either agent or account
• the API key scope and policy summary
• the current workspace and tenant binding
• the agent identity when the key is AGENT-scoped
• resolved permissions and warnings
• capability flags such as whether vault metadata writes are available for the current machine identity

This is the recommended first call for automation that needs to understand its current tenant context, policy limits, or available write paths.

Vault Metadata vs Secret Values

Vault metadata such as vault names, item names, field labels, and websites is not end-to-end encrypted.

That metadata is protected by encryption in transit and at rest. Read responses can include signed summary/detail checkpoints so zero-trust runtimes can verify metadata snapshots. Only field values, such as encryptedValue on creates and value on reads/updates, are end-to-end encrypted v3 vault envelopes.

Agent Orchestration

AGENT runtimes can do more than read secrets when they also receive:

• the tenant role TENANT_AGENT_MANAGER
• machine endpoint permissions such as machine.agent.all and machine.permissions.all

With that combination, an agent can:

• list agents in its tenant
• create subordinate agents and receive their one-time API keys
• assign direct tenant roles to those agents
• manage project or vault access through the machine permissions API

The most practical delegated-orchestration flow is:

1. GET /agent to reuse an existing domainTenantId
2. POST /agent to create a subordinate runtime
3. PATCH /agent/:id/tenant-roles to grant direct tenant roles such as TENANT_AGENT_MANAGER
4. POST /permissions/PROJECT/:id/set-permissions to delegate project access

This is intentionally separate from vault and vault-item write permissions. Attachment management, procurement, and outbound machine webhooks now exist on the same headless machine surface, but they still require their own endpoint permissions and, in some cases, additional tenant or org roles.

Capability Feedback

If the CLI, Node SDK, MCP server, or current raw machine API is missing a capability the agent needs, submit product feedback through:

• POST /feedback
• or the dedicated Submit Feedback guide

This endpoint is AGENT-only. It stores the feedback, forwards it to the internal feedback inbox, and is intended specifically for "I tried to do X, but R4 does not support it yet" reports.

Do not include secret values, plaintext credentials, or private user data in the feedback body.

Authentication

Machine API requests accept either an API key or a CLI device access token. For the agent password-manager flow, the runtime also needs its local private key.

• API key transport: X-API-Key: {accessKey}.{secret}
• Alternative transport: Authorization: ApiKey {accessKey}.{secret}
• Account token transport: Authorization: Bearer <token> with x-r4-session-surface: cli and x-r4-device-installation-id
• Private key usage: local only, never sent to R4

See Authentication and Keys for the full setup.

API Key Policies

Every API-key machine request must pass two checks:

1. the API key's scope (AGENT, USER, TENANT, or ORG)
2. the API key's machine policy for the endpoint being called

Account access-token requests are user-backed and receive the machine permissions allowed for USER-backed callers, excluding the access-management write families (machine.org_admin.write, machine.tenant_admin.write, machine.user_manager.write, machine.permissions.write). They are useful for personal CLI/SDK automation, but they do not grant AGENT-only capabilities such as machine.agent.public_key.write or machine.feedback.write; admin-write automation needs a scoped API key with an explicit policy. Keys that predate machine policies resolve to their scope's safe default bundle instead of full access — rotate them to pin an explicit policy.

When you create a key, you can choose grouped grants or individual permissions.

For an AGENT runtime, the fastest setup is machine.all. A tighter AGENT policy usually includes machine.agent.all, machine.vault.read, machine.vault.secret.read, machine.vault.sync.read, and optionally machine.search.read, machine.project.read, machine.permissions.all, machine.monitoring.read, or machine.feedback.write when the runtime should be able to report unsupported product gaps on its own.

Fine-grained identity discovery uses the atomic permission machine.me.read.

Monitoring routes intentionally split by sensitivity:

• GET /monitoring/metric-stats and GET /monitoring/entity-counts are filtered to what the current machine session can already access
• GET /monitoring/system-stats and GET /monitoring/session-stats require a global-admin-backed machine key in addition to the monitoring permission

Scope and Write Behavior

R4 supports multiple API-key scopes, but the password-manager path described on this website is specifically for AGENT runtimes.

Important current constraint:

• AGENT-scoped machine API keys are the supported runtime path for zero-trust reads and machine vault/vault-item writes when their policy grants the needed endpoint permissions
• USER, TENANT, and ORG machine API keys can use the same write routes when their policy and asset access allow it
• vault attachment upload/download parity is available through /attachments/:vaultId/*
• Pincer license purchase/termination and outbound eventing are available through /licenses/* and /webhook/*

See Current Limitations for the exact wording to use.

Error Format

All machine API errors use a JSON error envelope:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message"
  }
}

Common machine API errors:

Other Machine API Domains

The machine API also includes:

• full project lifecycle management, including member and agent assignment
• domain and DNS management, including richer domain-manager email and SSL routes
• billing helpers plus credit-transaction, billing-overview, crypto-funding-intent, and distributor-charge reads/writes
• license environment bundles for provisioned licenses through GET /licenses/:licenseInstanceId/environment
• monitoring reads for machine observers and anomaly-detection automations
• AGENT feedback submission when the current SDK, MCP, or machine API surface is missing a needed capability
• wrapped-key and user-key-pair management for zero-trust encryption flows
• integration, intelligence-provider/token-provider, user-manager, tenant-admin, and org-admin surfaces
• contract and order management surfaces

Managed token-provider wrappers now live on the machine surface too: the runtime can fetch a provider-scoped zero-trust bundle, decrypt the secret locally, preflight budget state with R4, call the vendor directly, and then report finalized usage back to R4.

Those capabilities are real, but they are secondary to the agent password-manager flow this site now emphasizes.

Next Reading

• API Reference
• Detailed Machine API Reference
• Machine Endpoint Inventory
• Agent Orchestration
• Permission Management
• Submit Feedback
• Register or Rotate Agent Public Key
• List Vault Environment Fields
• Update Vault
• List Vault Items
• Update Vault Item
• Move Vault Item
• Get Vault Field Value
• Get Vault Item Detail