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. authenticate with an AGENT API key
2. keep a local PEM-encoded RSA private key
3. register the matching public key with POST /vault/public-key
4. let operators grant vault-backed access only after that first registration succeeds
5. list the vaults it can access
6. retrieve the wrapped vault key and signer directory
7. verify the returned trust metadata and checkpoints
8. decrypt the shared secrets locally

The MCP server, CLI, and Node SDK already implement this flow for you.

For brand-new agent-only organizations, POST /api/v1/auth/auth/register-agent can now bootstrap the org, tenant, default internal domain, first AGENT API key, and optionally the first runtime public key in one headless call. That bootstrap now also requires a saved Stripe payment method id and an initial prepaid top-off of at least $20; the org only becomes active after that billing step succeeds. As with the rest of the auth POST surface, send X-Requested-With: R4Client.

If that brand-new org needs prepaid credit, the same AGENT runtime can now create a crypto funding intent and top up the org 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.

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 org 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 org 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 API key scope and policy summary
• the current org 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 whether it still needs a registered runtime signer before AGENT-scoped vault metadata writes will succeed.

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 only protected by encryption in transit and at rest, then authenticated with signed checkpoints. Only field values, such as encryptedValue on writes and value on reads, 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 the trust requirements for vault metadata writes. AGENT keys can already create and archive vault metadata when they sign checkpoints with their active runtime key. 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

All machine API requests require an API key. 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}
• Private key usage: local only, never sent to R4

See Authentication and Keys for the full setup.

API Key Policies

Every 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

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 checkpoint-signed vault metadata writes when the runtime has an active registered encryption key
• USER, TENANT, and ORG machine API keys can use the same write routes when they are backed by an active user key pair
• vault attachment upload/download parity is available through /attachments/:vaultId/*
• machine procurement and outbound eventing are available through /marketplace/* 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, and crypto-funding-intent reads/writes
• monitoring reads for machine observers and anomaly-detection automations
• AGENT feedback submission when the current CLI, 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
• license, contract, order, and product 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 Agent Public Key
• Update Vault
• List Vault Items
• Update Vault Item
• Move Vault Item
• Get Vault Field Value
• Get Vault Item Detail