Machine API Reference

This document is the detailed endpoint reference for the machine API.

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

1. R4 for Agents
2. Authentication and Keys
3. CLI or Node SDK
4. API Reference
5. Machine Endpoint Inventory

API Key Policies

Every machine request must satisfy both:

1. the API key scope (AGENT, USER, TENANT, ORG)
2. the machine permission required by the endpoint

Grouped grants are expanded when the key is created, so runtime authorization checks stay atomic and auditable.

Common grouped grants

Atomic endpoint families

Expanded Thin Proxy Surface

The machine API now proxies most of the platform external API surface rather than re-implementing separate business logic. That includes:

• project lifecycle parity, including vault/license associations and project member/agent management
• vault-adjacent management such as vault-item activity/change-log routes, vault groups/imports, wrapped keys, and user key pairs
• tenant/org admin, integrations, intelligence providers, billing, and commercial/license surfaces
• monitoring reads for machine observers; metric-stats, entity-counts, request-events, audit-events, and vault-activity-events stay scoped to the authenticated machine session, while system-stats and session-stats are reserved for global-admin-backed keys
• machine-native metadata discovery through POST /search plus persist-style full or delta vault sync through GET /vault/sync
• vault attachment upload/download parity through /attachments/:vaultId/*
• machine-owned procurement flows through /marketplace/*
• outbound webhook subscriptions and delivery history through /webhook/*

For the audited controller-by-controller route list, see Machine Endpoint Inventory.

POST /project also accepts an optional domainTenantId. Pass it explicitly for ORG-scoped keys or when a tenant has multiple domain-tenant bindings and you need a specific target.

Prepaid Crypto Funding

Machine callers can now top up org credit from any wallet that holds USDC on Base. The agent does not need a Stripe account.

Routes:

• POST /api/v1/machine/billing/crypto-funding-intents
• GET /api/v1/machine/billing/crypto-funding-intents
• GET /api/v1/machine/billing/crypto-funding-intents/:id

Permissions:

• create requires machine.billing.write
• list/detail require machine.billing.read

Flow:

1. Create a funding intent with the USD amount you want to add.
2. R4 returns a provider-neutral response with the exact tokenCurrency, network, depositAddress, expiresAt, and status fields.
3. Send the exact amount from any USDC Base wallet to that deposit address.
4. Stripe deposit mode settles the payment in the background, and R4 credits the org through the existing prepaid CreditTransaction ledger.
5. Poll the funding-intent route, GET /billing/balance, or GET /billing/readiness until the credit is available.

This is a prepaid top-up flow. It is intentionally separate from future x402 pay-per-request flows.

Managed Token Providers

The machine API now exposes a managed token-provider path for SDK/runtime wrappers that want budget-aware vendor calls without proxying the vendor request through R4.

Routes:

• GET /api/v1/machine/intelligence-provider/:id/runtime
• POST /api/v1/machine/intelligence-provider/:id/authorize-usage
• POST /api/v1/machine/intelligence-provider/:id/report-usage

What this does:

• proves access to the token provider through the normal permission graph
• returns only wrapped key material plus ciphertext for local secret decryption
• prices usage server-side from trusted provider metadata
• records finalized usage into the spend-governance path after the direct vendor call completes

What this does not do:

• proxy the vendor request through R4
• make bypass-proof metering for callers that deliberately ignore the managed SDK path
• reserve budget yet; the current authorize step only checks whether the subject chain is already blocked

Identity and Context Discovery

Use /me when an agent or headless integration needs to confirm the current scope, tenant binding, or write-path constraints before taking action.

Requirements:

• machine.me.read

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

Key response areas:

• apiKey.scope and apiKey.summary tell you what policy was enforced
• org, tenant, and agent describe the current principal context
• session returns the current tenant, security-group, and project state
• capabilities.vaultWriteConstraint explains whether vault metadata writes are blocked by policy, a missing AGENT runtime key, or a synthetic non-agent session
• warnings highlights important conditions such as legacy full-access keys or missing agent public-key registration

Agent Orchestration

See Agent Orchestration for the dedicated lifecycle guide.

Agent-orchestration endpoints add a second authorization layer on top of machine permissions:

1. the key must include machine.agent.read / machine.agent.write
2. the authenticated session must also hold TENANT_AGENT_MANAGER (or an admin bypass)

Discover the current tenant context

Use this when you need a valid domainTenantId for a new subordinate agent.

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

The list response includes each agent's domainTenantId, which you can reuse when creating another agent in the same tenant.

Create a subordinate agent

curl -X POST https://r4.dev/api/v1/machine/agent -H "X-API-Key: YOUR_AGENT_KEY" -H "Content-Type: application/json" -d '{"name":"Steward Agent","domainTenantId":"DOMAIN_TENANT_ID","securityGroupIds":[],"permissions":["machine.agent.all","machine.permissions.all","machine.project.read"]}'

The response returns the new agent id, plus a one-time accessKey and accessSecret. Combine those as accessKey.accessSecret to authenticate as the new agent.

Grant a direct tenant role to an agent

curl -X PATCH https://r4.dev/api/v1/machine/agent/AGENT_ID/tenant-roles -H "X-API-Key: YOUR_AGENT_KEY" -H "Content-Type: application/json" -d '{"roles":["TENANT_AGENT_MANAGER"]}'

Read an agent's direct and inherited roles

curl https://r4.dev/api/v1/machine/agent/AGENT_ID/tenant-roles -H "X-API-Key: YOUR_AGENT_KEY"

Archive an agent

curl -X PATCH https://r4.dev/api/v1/machine/agent/AGENT_ID/archive -H "X-API-Key: YOUR_AGENT_KEY"

Update an agent

curl -X PATCH https://r4.dev/api/v1/machine/agent/AGENT_ID -H "X-API-Key: YOUR_AGENT_KEY" -H "Content-Type: application/json" -d '{"name":"Steward Agent v2","securityGroupIds":["SECURITY_GROUP_ID"]}'

Link an agent API key to a vault item

curl -X PATCH https://r4.dev/api/v1/machine/agent/AGENT_ID/vault-item -H "X-API-Key: YOUR_AGENT_KEY" -H "Content-Type: application/json" -d '{"vaultItemId":"VAULT_ITEM_ID"}'

Regenerate an agent API key

curl -X POST https://r4.dev/api/v1/machine/agent/AGENT_ID/regenerate-api-key -H "X-API-Key: YOUR_AGENT_KEY"

Capability Feedback

Use the feedback endpoint when an AGENT runtime is blocked by a missing CLI, SDK, MCP, or raw machine-API capability.

Requirements:

• AGENT-scoped API key
• machine.feedback.write or machine.feedback.all

curl -X POST https://r4.dev/api/v1/machine/feedback -H "X-API-Key: YOUR_AGENT_KEY" -H "Content-Type: application/json" -d '{"surface":"CLI","summary":"Need project-aware secret lookup","details":"The CLI can read secrets, but it cannot first resolve the right project and then narrow the vault lookup.","desiredOutcome":"Add a CLI command or SDK helper that resolves project context before secret retrieval."}'

R4 stores the feedback first, then sends a best-effort internal notification email. Do not include secret values, plaintext credentials, tokens, or private user data in this payload.

For the field-level contract, see Submit Feedback.

Permission Management

See Permission Management for the dedicated guide covering helper selectors, project permissions, vault permissions, and vault-item permissions.

Permission-management endpoints require both:

1. machine.permissions.read / machine.permissions.write
2. ADMIN access to the target asset

For delegated orchestration, start with project permissions. Project writes do not require the extra checkpoint material that vault permission writes may need.

set-permissions replaces the full permission list, so include every entry you want to keep, including the acting agent's own ADMIN row.

Supported assetType values include PROJECT, VAULT, VAULT_ITEM, LICENSE_INSTANCE, and ENCRYPTION_KEY.

Replace project permissions

curl -X POST https://r4.dev/api/v1/machine/permissions/PROJECT/PROJECT_ID/set-permissions -H "X-API-Key: YOUR_AGENT_KEY" -H "Content-Type: application/json" -d '{"permissions":[{"id":"MASTER_AGENT_ID","name":"Master Agent","type":"agent","avatar":null,"isDefault":null,"access":"ADMIN"},{"id":"CHILD_AGENT_ID","name":"Child Agent","type":"agent","avatar":null,"isDefault":null,"access":"READ"}]}'

Inspect current project permissions

curl https://r4.dev/api/v1/machine/permissions/PROJECT/PROJECT_ID/permissions -H "X-API-Key: YOUR_AGENT_KEY"

Replace vault permissions

Vault permission writes require a signed permissionCheckpoint that exactly matches the submitted direct permission list.

curl -X POST https://r4.dev/api/v1/machine/permissions/VAULT/VAULT_ID/set-permissions -H "X-API-Key: YOUR_AGENT_KEY" -H "Content-Type: application/json" -d '{"permissions":[{"id":"MASTER_AGENT_ID","name":"Master Agent","type":"agent","avatar":null,"isDefault":null,"access":"ADMIN"},{"id":"CHILD_AGENT_ID","name":"Child Agent","type":"agent","avatar":null,"isDefault":null,"access":"READ"}],"permissionCheckpoint":{"checkpoint":{"assetId":"VAULT_ID","assetType":"VAULT","version":4,"permissions":[{"entityId":"MASTER_AGENT_ID","entityType":"agent","access":"ADMIN"},{"entityId":"CHILD_AGENT_ID","entityType":"agent","access":"READ"}]},"signerUserKeyPairId":"USER_KEY_PAIR_ID","signature":"base64-signature"}}'

Replace vault-item permissions

Vault-item permission writes use the same checkpoint-backed request shape as vault writes, but parent-vault access still applies irrespective of direct item settings.

curl -X POST https://r4.dev/api/v1/machine/permissions/VAULT_ITEM/VAULT_ITEM_ID/set-permissions -H "X-API-Key: YOUR_AGENT_KEY" -H "Content-Type: application/json" -d '{"permissions":[{"id":"CHILD_AGENT_ID","name":"Child Agent","type":"agent","avatar":null,"isDefault":null,"access":"READ"}],"permissionCheckpoint":{"checkpoint":{"assetId":"VAULT_ITEM_ID","assetType":"VAULT_ITEM","version":7,"permissions":[{"entityId":"CHILD_AGENT_ID","entityType":"agent","access":"READ"}]},"signerUserKeyPairId":"USER_KEY_PAIR_ID","signature":"base64-signature"}}'

Domain Manager

The Domain Manager API provides programmatic access to DNS management for domains in your organization.

Get DNS Records

Retrieves all DNS records configured for a domain managed by your organization.

GET /api/v1/machine/domain-manager/dns-records

Query Parameters

Headers

Response

Success (200 OK)

{
  "domain": "example.com",
  "records": [
    {
      "type": "A",
      "name": "@",
      "value": "192.168.1.1",
      "ttl": 300
    },
    {
      "type": "CNAME",
      "name": "www",
      "value": "example.com.",
      "ttl": 300
    },
    {
      "type": "MX",
      "name": "@",
      "value": "mail.example.com.",
      "ttl": 300,
      "mxPref": 10
    },
    {
      "type": "TXT",
      "name": "@",
      "value": "v=spf1 include:_spf.google.com ~all",
      "ttl": 300
    }
  ]
}

Response Fields

Error Responses

401 Unauthorized - Invalid or missing API key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Please provide your API key in the X-API-Key header."
  }
}

403 Forbidden - Domain not managed through R4

{
  "error": {
    "code": "domain_not_managed",
    "message": "The domain \"example.com\" is not managed through R4. DNS records can only be retrieved for domains purchased through the R4 platform."
  }
}

404 Not Found - Domain not found in your organization

{
  "error": {
    "code": "domain_not_found",
    "message": "The domain \"example.com\" was not found in your organization or you do not have access to it."
  }
}

Example Request

curl -X GET "https://r4.dev/api/v1/machine/domain-manager/dns-records?domain=example.com" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef"

Use Cases

• Infrastructure auditing: Verify DNS configuration across your domains
• Monitoring: Build dashboards showing current DNS settings
• Pre-deployment checks: Validate DNS before deploying applications
• Documentation: Automatically document your DNS configuration

Notes

• Only domains purchased through R4 (internalPurchase: true) can have their DNS records retrieved
• External domains (registered elsewhere) are not accessible through this endpoint
• The domain must be associated with a tenant in your organization

Add DNS Record

Adds a new DNS record to a domain managed by your organization.

POST /api/v1/machine/domain-manager/dns-records

Headers

Request Body

Example Request Body

{
  "domain": "example.com",
  "record": {
    "type": "A",
    "name": "www",
    "value": "192.168.1.1",
    "ttl": 300
  }
}

Response

Success (200 OK)

Returns all DNS records for the domain, including the newly added record.

{
  "domain": "example.com",
  "records": [
    {
      "type": "A",
      "name": "@",
      "value": "192.168.1.1",
      "ttl": 300
    },
    {
      "type": "A",
      "name": "www",
      "value": "192.168.1.1",
      "ttl": 300
    },
    {
      "type": "CNAME",
      "name": "mail",
      "value": "example.com.",
      "ttl": 300
    }
  ]
}

Error Responses

401 Unauthorized - Invalid or missing API key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Please provide your API key in the X-API-Key header."
  }
}

403 Forbidden - Domain not managed through R4

{
  "error": {
    "code": "domain_not_managed",
    "message": "The domain \"example.com\" is not managed through R4. DNS records can only be modified for domains purchased through the R4 platform."
  }
}

404 Not Found - Domain not found in your organization

{
  "error": {
    "code": "domain_not_found",
    "message": "The domain \"example.com\" was not found in your organization or you do not have access to it."
  }
}

Example Request

curl -X POST "https://r4.dev/api/v1/machine/domain-manager/dns-records" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "record": {
      "type": "A",
      "name": "www",
      "value": "192.168.1.1",
      "ttl": 300
    }
  }'

Use Cases

• Infrastructure automation: Automatically configure DNS when provisioning servers
• CI/CD pipelines: Set up DNS records as part of deployment workflows
• Subdomain management: Programmatically create subdomains for new services
• Email configuration: Add MX, SPF, and DKIM records for email setup
• Domain verification: Add TXT records for third-party service verification

Notes

• Only domains purchased through R4 (internalPurchase: true) can have their DNS records modified
• External domains (registered elsewhere) cannot be modified through this endpoint
• The domain must be associated with a tenant in your organization
• DNS changes may take time to propagate (typically 5 minutes to 48 hours depending on TTL)
• The response includes all DNS records for the domain, not just the newly added one

Project Manager

The Project Manager API provides programmatic access to project creation, listing, and detailed resource information. Projects are organizational units that contain vaults, licenses, and license groups.

List Projects

Retrieves a list of all non-archived projects accessible to the authenticated API key.

GET /api/v1/machine/project

Headers

Response

Success (200 OK)

{
  "projects": [
    {
      "id": "507f1f77bcf86cd799439014",
      "name": "Production Infrastructure",
      "externalId": "PROJ-001",
      "description": "Contains all production environment resources",
      "vaultsCount": 5,
      "licensesCount": 12,
      "licenseGroupsCount": 3,
      "archivedAt": null
    },
    {
      "id": "507f1f77bcf86cd799439015",
      "name": "Development Environment",
      "externalId": "PROJ-002",
      "description": "Development and testing resources",
      "vaultsCount": 2,
      "licensesCount": 4,
      "licenseGroupsCount": 1,
      "archivedAt": null
    }
  ]
}

Response Fields

Project Summary Fields

Error Responses

401 Unauthorized - Invalid or missing API key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Please provide your API key in the X-API-Key header."
  }
}

Example Request

curl -X GET "https://r4.dev/api/v1/machine/project" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef"

Create Project

Creates a new project in the organization.

POST /api/v1/machine/project

Headers

Request Body

Response

Success (201 Created)

{
  "id": "507f1f77bcf86cd799439014"
}

Response Fields

Error Responses

400 Bad Request - Invalid request body

{
  "error": {
    "code": "project_creation_failed",
    "message": "Failed to create the project. Please verify your input and try again."
  }
}

401 Unauthorized - Invalid or missing API key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Please provide your API key in the X-API-Key header."
  }
}

Example Request

curl -X POST "https://r4.dev/api/v1/machine/project" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Infrastructure",
    "externalId": "PROJ-001",
    "description": "Contains all production environment resources"
  }'

Get Project Details

Retrieves detailed information about a project including all associated vaults, licenses, and license groups.

GET /api/v1/machine/project/:id

Path Parameters

Headers

Response

Success (200 OK)

{
  "id": "507f1f77bcf86cd799439014",
  "name": "Production Infrastructure",
  "externalId": "PROJ-001",
  "description": "Contains all production environment resources",
  "domainTenantId": "507f1f77bcf86cd799439016",
  "vaultsCount": 5,
  "licensesCount": 12,
  "licenseGroupsCount": 3,
  "createdAt": "2026-01-15T10:30:00.000Z",
  "createdBy": "507f1f77bcf86cd799439017",
  "archivedAt": null,
  "vaults": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Production Secrets",
      "isEncrypted": true
    }
  ],
  "licenses": [
    {
      "id": "507f1f77bcf86cd799439012",
      "name": "Enterprise License",
      "type": "internal"
    },
    {
      "id": "507f1f77bcf86cd799439018",
      "name": "Manual License Entry",
      "type": "manual"
    }
  ],
  "licenseGroups": [
    {
      "id": "507f1f77bcf86cd799439013",
      "name": "Development Team Licenses"
    }
  ]
}

Response Fields

Vault Object Fields

License Object Fields

License Group Object Fields

Error Responses

401 Unauthorized - Invalid or missing API key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Please provide your API key in the X-API-Key header."
  }
}

404 Not Found - Project not found in your organization

{
  "error": {
    "code": "project_not_found",
    "message": "The project with ID \"507f1f77bcf86cd799439014\" was not found in your organization or you do not have access to it."
  }
}

Example Request

curl -X GET "https://r4.dev/api/v1/machine/project/507f1f77bcf86cd799439014" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef"

Notes

• The project must belong to your organization
• The API key must have access to the tenant associated with the project
• Only non-archived vaults, licenses, and license groups are included in the response

Vault Manager

The Vault Manager API provides full programmatic access to vault management — creating vaults, managing vault items, and retrieving secrets.

Create Vault

Creates a new encrypted vault with a client-signed empty summary checkpoint.

POST /api/v1/machine/vault

Headers

Request Body

Response

Success (201 Created)

{
  "id": "507f1f77bcf86cd799439016"
}

Notes

• Requires a USER, TENANT, or ORG API key backed by an active user key pair
• AGENT-scoped machine API keys can write when signerEncryptionKeyId matches the agent's active registered encryption key
• summaryCheckpoint.items and summaryCheckpoint.groups must both be empty on create
• If projectId is provided, the project is additionally granted WRITE access

Example Request

curl -X POST "https://r4.dev/api/v1/machine/vault" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "507f1f77bcf86cd799439016",
    "summaryCheckpoint": {
      "checkpoint": {
        "vaultId": "507f1f77bcf86cd799439016",
        "version": 1,
        "name": "Production Secrets",
        "dataClassification": "CONFIDENTIAL",
        "currentDekVersion": 1,
        "items": [],
        "groups": []
      },
      "signerUserKeyPairId": "507f1f77bcf86cd799439099",
      "signature": "base64-signature"
    },
    "name": "Production Secrets",
    "projectId": "507f1f77bcf86cd799439014",
    "dataClassification": "CONFIDENTIAL"
  }'

List Vaults

Returns all accessible vaults, optionally filtered by project.

GET /api/v1/machine/vault

Query Parameters

Response

Success (200 OK)

{
  "vaults": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Production Secrets",
      "isEncrypted": true,
      "encryptionKeyId": "507f1f77bcf86cd799439015",
      "dataClassification": "CONFIDENTIAL",
      "itemCount": 12,
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  ]
}

Example Request

curl -X GET "https://r4.dev/api/v1/machine/vault?projectId=507f1f77bcf86cd799439014" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef"

Get Vault Detail

Returns detailed information about a specific vault.

GET /api/v1/machine/vault/:vaultId

Path Parameters

Response

Success (200 OK)

{
  "id": "507f1f77bcf86cd799439011",
  "name": "Production Secrets",
  "isEncrypted": true,
  "encryptionKeyId": "507f1f77bcf86cd799439015",
  "dataClassification": "CONFIDENTIAL",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "createdBy": "507f1f77bcf86cd799439017",
  "itemCount": 12
}

Vault metadata note: vault names, item names, field labels, and websites are 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 are end-to-end encrypted v3 vault envelopes.

Update Vault

Updates vault metadata such as the vault name or data classification.

PATCH /api/v1/machine/vault/:id/update

Request Body

Notes

• Both checkpoints must be fresh and signed by an active user key owned by the acting org user.
• The vault name in this request and its checkpoints is metadata, so it is not end-to-end encrypted.
• This is the vault-level rename/update path. See Update Vault for the full walkthrough.

Archive Vault

Archives (soft-deletes) a vault with a client-signed replacement summary checkpoint. The vault and its items are retained for audit purposes.

DELETE /api/v1/machine/vault/:vaultId

Path Parameters

Request Body

Response

Success (204 No Content)

No response body.

Notes

• Requires a USER, TENANT, or ORG API key backed by an active user key pair
• AGENT-scoped machine API keys can write when signerEncryptionKeyId matches the agent's active registered encryption key
• The replacement summaryCheckpoint should usually preserve the current vault item/group snapshot and only advance the signed metadata version during the archive transition

No response body.

Create Vault Item

Creates a new vault item with client-encrypted field values plus signed vault/item checkpoints.

POST /api/v1/machine/vault/:vaultId/items

Path Parameters

Request Body

Field Object

Response

Success (201 Created)

{
  "id": "507f1f77bcf86cd799439018"
}

Notes

• Requires a USER, TENANT, or ORG API key backed by an active user key pair
• AGENT-scoped machine API keys can write when signerEncryptionKeyId matches the agent's active registered encryption key
• The vault name, item name, field name, and websites metadata in this request are not end-to-end encrypted.
• The backend stores encryptedValue as-is and does not decrypt it

Example Request

curl -X POST "https://r4.dev/api/v1/machine/vault/507f1f77bcf86cd799439011/items" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "507f1f77bcf86cd799439018",
    "summaryCheckpoint": {
      "checkpoint": {
        "vaultId": "507f1f77bcf86cd799439011",
        "version": 9,
        "name": "Production Secrets",
        "dataClassification": "CONFIDENTIAL",
        "currentDekVersion": 3,
        "items": [
          {
            "id": "507f1f77bcf86cd799439018",
            "name": "Production Database",
            "type": "LOGIN",
            "websites": ["https://db.example.com"],
            "groupId": null
          }
        ],
        "groups": []
      },
      "signerUserKeyPairId": "507f1f77bcf86cd799439099",
      "signature": "base64-signature"
    },
    "detailCheckpoint": {
      "checkpoint": {
        "vaultItemId": "507f1f77bcf86cd799439018",
        "vaultId": "507f1f77bcf86cd799439011",
        "version": 1,
        "name": "Production Database",
        "type": "LOGIN",
        "websites": ["https://db.example.com"],
        "groupId": null,
        "fields": [
          {
            "id": "507f1f77bcf86cd799439019",
            "name": "Username",
            "type": "TEXT",
            "order": 0,
            "fieldInstanceIds": ["507f1f77bcf86cd799439051"],
            "assetIds": []
          }
        ]
      },
      "signerUserKeyPairId": "507f1f77bcf86cd799439099",
      "signature": "base64-signature"
    },
    "name": "Production Database",
    "type": "LOGIN",
    "websites": ["https://db.example.com"],
    "fields": [
      {
        "id": "507f1f77bcf86cd799439019",
        "fieldInstanceId": "507f1f77bcf86cd799439051",
        "name": "Username",
        "type": "TEXT",
        "encryptedValue": "{\"v\":3,\"iv\":\"...\",\"t\":\"...\",\"d\":\"...\"}"
      },
      {
        "id": "507f1f77bcf86cd799439020",
        "fieldInstanceId": "507f1f77bcf86cd799439052",
        "name": "Password",
        "type": "PASSWORD",
        "encryptedValue": "{\"v\":3,\"iv\":\"...\",\"t\":\"...\",\"d\":\"...\"}"
      }
    ]
  }'

List Vault Items

Returns all non-archived items in a vault with the signed summary-checkpoint metadata a zero-trust runtime needs before trusting item names, websites, or group structure.

GET /api/v1/machine/vault/:vaultId/items

Path Parameters

Response

Success (200 OK)

{
  "vaultId": "507f1f77bcf86cd799439011",
  "vaultName": "Production Secrets",
  "dataClassification": "CONFIDENTIAL",
  "currentDekVersion": 3,
  "summaryCheckpoint": {
    "checkpoint": {
      "vaultId": "507f1f77bcf86cd799439011",
      "version": 9,
      "name": "Production Secrets",
      "dataClassification": "CONFIDENTIAL",
      "currentDekVersion": 3,
      "items": [
        {
          "id": "507f1f77bcf86cd799439018",
          "name": "Production Database",
          "type": "LOGIN",
          "websites": ["https://db.example.com"],
          "groupId": null
        }
      ],
      "groups": []
    },
    "signerUserKeyPairId": "507f1f77bcf86cd799439099",
    "signature": "base64-signature"
  },
  "items": [
    {
      "id": "507f1f77bcf86cd799439018",
      "name": "Production Database",
      "type": "LOGIN",
      "websites": ["https://db.example.com"],
      "groupId": null,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "fieldCount": 2
    }
  ],
  "vaultItemGroups": [],
  "count": 1
}

Notes

• vaultName, item name, and websites are metadata, so they are not end-to-end encrypted
• Zero-trust runtimes should verify summaryCheckpoint against GET /vault/:vaultId/public-keys
• currentDekVersion binds the item listing to the current wrapped-DEK generation
• vaultItemGroups provides the group structure covered by the signed checkpoint

Get Vault Field Value

Returns the latest stored payload for one field, plus the parent signed detail checkpoint so a runtime can authenticate the field metadata locally without fetching sibling field values.

GET /api/v1/machine/vault/:vaultId/fields/:fieldId

Path Parameters

Response

Success (200 OK)

{
  "id": "507f1f77bcf86cd799439020",
  "name": "Password",
  "type": "PASSWORD",
  "order": 1,
  "fieldInstanceId": "507f1f77bcf86cd799439052",
  "fieldInstanceIds": ["507f1f77bcf86cd799439052"],
  "assetId": null,
  "assetIds": [],
  "value": "{\"v\":3,\"iv\":\"...\",\"t\":\"...\",\"d\":\"...\"}",
  "vaultId": "507f1f77bcf86cd799439011",
  "vaultItemId": "507f1f77bcf86cd799439018",
  "vaultItemName": "Production Database",
  "detailCheckpoint": {
    "checkpoint": {
      "vaultItemId": "507f1f77bcf86cd799439018",
      "vaultId": "507f1f77bcf86cd799439011",
      "version": 12,
      "name": "Production Database",
      "type": "LOGIN",
      "websites": ["https://db.example.com"],
      "groupId": null,
      "fields": [
        {
          "id": "507f1f77bcf86cd799439019",
          "name": "Username",
          "type": "TEXT",
          "order": 0,
          "fieldInstanceIds": ["507f1f77bcf86cd799439051"],
          "assetIds": []
        },
        {
          "id": "507f1f77bcf86cd799439020",
          "name": "Password",
          "type": "PASSWORD",
          "order": 1,
          "fieldInstanceIds": ["507f1f77bcf86cd799439052"],
          "assetIds": []
        }
      ]
    },
    "signerUserKeyPairId": "507f1f77bcf86cd799439099",
    "signature": "base64-signature"
  }
}

Notes

• Use this when you already know the fieldId and want the narrowest possible read
• The field name, vaultItemName, and checkpoint websites metadata are not end-to-end encrypted
• fieldInstanceId is the latest active instance used for value; fieldInstanceIds contains the full active instance set
• Verify that the matching field entry inside detailCheckpoint.checkpoint.fields matches the returned id, type, order, fieldInstanceIds, and assetIds
• Use POST /vault/public-key, GET /vault/:vaultId/wrapped-key, and GET /vault/:vaultId/public-keys to unwrap the vault DEK and verify the signer locally before decrypting value

Get Vault Item Detail

Returns full vault item detail including all fields, ciphertext values, and the signed detail checkpoint needed to authenticate the metadata locally.

GET /api/v1/machine/vault/:vaultId/items/:itemId

Path Parameters

Response

Success (200 OK)

{
  "id": "507f1f77bcf86cd799439018",
  "name": "Production Database",
  "type": "LOGIN",
  "websites": ["https://db.example.com"],
  "vaultId": "507f1f77bcf86cd799439011",
  "groupId": null,
  "fields": [
    {
      "id": "507f1f77bcf86cd799439019",
      "name": "Username",
      "type": "TEXT",
      "order": 0,
      "fieldInstanceIds": ["507f1f77bcf86cd799439051"],
      "assetIds": [],
      "value": "{\"v\":3,\"iv\":\"...\",\"t\":\"...\",\"d\":\"...\"}"
    },
    {
      "id": "507f1f77bcf86cd799439020",
      "name": "Password",
      "type": "PASSWORD",
      "order": 1,
      "fieldInstanceIds": ["507f1f77bcf86cd799439052"],
      "assetIds": [],
      "value": "{\"v\":3,\"iv\":\"...\",\"t\":\"...\",\"d\":\"...\"}"
    }
  ],
  "detailCheckpoint": {
    "checkpoint": {
      "vaultItemId": "507f1f77bcf86cd799439018",
      "vaultId": "507f1f77bcf86cd799439011",
      "version": 12,
      "name": "Production Database",
      "type": "LOGIN",
      "websites": ["https://db.example.com"],
      "groupId": null,
      "fields": [
        {
          "id": "507f1f77bcf86cd799439019",
          "name": "Username",
          "type": "TEXT",
          "order": 0,
          "fieldInstanceIds": ["507f1f77bcf86cd799439051"],
          "assetIds": []
        }
      ]
    },
    "signerUserKeyPairId": "507f1f77bcf86cd799439099",
    "signature": "base64-signature"
  }
}

Notes

• For client-encrypted vaults, every field value is returned as stored ciphertext
• The item name, field name, and websites metadata are not end-to-end encrypted
• Use POST /vault/public-key, GET /vault/:vaultId/wrapped-key, and GET /vault/:vaultId/public-keys as part of your client-side key-unwrapping flow
• Verify detailCheckpoint before trusting the item name, websites, or field layout
• Field type controls client masking, not whether a value is encrypted

Update Vault Item

Updates vault-item metadata and applies batched field mutations through the updates array.

PATCH /api/v1/machine/vault-item/:id/update

Request Body

Notes

• This is the field-edit path for machine callers. There is no separate per-field write endpoint.
• The item name, field name, and websites metadata in this request are not end-to-end encrypted.
• add creates a new field, update creates a new active field instance, and delete archives the field.
• See Update Vault Item for the full request shape.

Move Vault Item

Moves a vault item into another vault.

PATCH /api/v1/machine/vault-item/:id/move

Request Body

Notes

• Use this when the parent vault changes.
• See Move Vault Item for the complete request contract and example payload.

Archive Vault Item

Archives (soft-deletes) a vault item with a client-signed replacement summary checkpoint.

DELETE /api/v1/machine/vault/:vaultId/items/:itemId

Path Parameters

Request Body

Response

Success (204 No Content)

No response body.

Notes

• Requires a USER, TENANT, or ORG API key backed by an active user key pair
• AGENT-scoped machine API keys can write when signerEncryptionKeyId matches the agent's active registered encryption key

Register Agent Public Key

Registers the AGENT-scoped caller's active RSA public key. The private key stays on the agent runtime and never traverses the server.

POST /api/v1/machine/vault/public-key

Optional Header

• X-R4-Agent-Hostname: Best-effort runtime hostname claim sent by the official SDK/CLI. Stored only for operator visibility.

Request Body

{
  "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "previousEncryptionKeyId": "507f1f77bcf86cd799439015",
  "rotationSignature": "base64-signature"
}

Response

Success (201 Created)

{
  "encryptionKeyId": "507f1f77bcf86cd799439015",
  "publicKey": "-----BEGIN PUBLIC KEY-----\n...",
  "fingerprint": "b5d44d6c7c1c1d4b...",
  "previousEncryptionKeyId": "507f1f77bcf86cd799439010",
  "rotationSignature": "base64-signature"
}

Notes

• Requires an AGENT-scoped API key
• R4 records the observed client IP address and optional X-R4-Agent-Hostname claim on the agent so operators can see where the active key last registered
• Re-registering the same public key is idempotent
• The first successful registration is what makes the agent eligible for security-group, project, and direct vault access
• Existing pre-registration access is not retroactively wrapped to the new key
• Rotating to a new key requires a continuity signature from the previous private key
• Rotating to a different key while the old key still has vault-backed access requires a full replacement rewrappedVaultKeys batch
• Use the locally stored private key with GET /vault/:vaultId/wrapped-key to unwrap vault DEKs

DNS Record Types

The following DNS record types may be returned by the API:

A Record

Maps a domain to an IPv4 address.

{
  "type": "A",
  "name": "@",
  "value": "192.168.1.1",
  "ttl": 300
}

AAAA Record

Maps a domain to an IPv6 address.

{
  "type": "AAAA",
  "name": "@",
  "value": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
  "ttl": 300
}

CNAME Record

Creates an alias from one domain to another.

{
  "type": "CNAME",
  "name": "www",
  "value": "example.com.",
  "ttl": 300
}

MX Record

Specifies mail servers for the domain. Lower mxPref values indicate higher priority.

{
  "type": "MX",
  "name": "@",
  "value": "mail.example.com.",
  "ttl": 300,
  "mxPref": 10
}

TXT Record

Contains arbitrary text data, commonly used for SPF, DKIM, and domain verification.

{
  "type": "TXT",
  "name": "@",
  "value": "v=spf1 include:_spf.google.com ~all",
  "ttl": 300
}

NS Record

Specifies authoritative nameservers for the domain.

{
  "type": "NS",
  "name": "@",
  "value": "ns1.example.com.",
  "ttl": 86400
}

Pagination

Currently, endpoints return all results in a single response. Future endpoints may support pagination with the following format:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "totalPages": 3
  }
}

Query parameters for paginated endpoints:

Changelog

v1.9.0 (April 2026)

• POST /auth/auth/register-agent now requires a saved Stripe payment method id plus an initial prepaid top-off of at least $20, and the new agent-only org stays pending until that billing step succeeds

v1.8.0 (March 2026)

• Added GET /vault/sync so machine-authenticated runtimes can reuse the full or delta persist sync contract
• Added POST /search for machine-visible vault, field-label, and license metadata discovery
• Expanded POST /auth/auth/register-agent bootstrap coverage so a new agent-only org can optionally register its first runtime public key and custom AGENT machine-policy grants in the same flow

v1.7.0 (March 2026)

• Documented the existing PATCH /vault/:id/update, PATCH /vault-item/:id/update, and PATCH /vault-item/:id/move write routes
• Added the audited Machine Endpoint Inventory for the full controller-level route list

v1.6.0 (March 2026)

• Added GET /vault/:vaultId/fields/:fieldId for narrow single-field reads that still return the parent signed detail checkpoint

v1.5.0 (March 2026)

• Removed the legacy GET /vault/env/:projectId plaintext env endpoint
• Added signed checkpoint metadata to GET /vault/:vaultId/items and GET /vault/:vaultId/items/:itemId
• Vault archive and vault-item archive now require a client-signed replacement summary checkpoint

v1.4.0 (March 2026)

• Removed server-held agent private-key retrieval from the Vault Manager API
• Added POST /vault/public-key so AGENT-scoped runtimes register or rotate their own public key locally

v1.3.0 (March 2026)

• Added Vault Manager API with full vault CRUD:
  • POST /vault — Create encrypted vault
  • GET /vault — List vaults (with optional project filter)
  • GET /vault/:vaultId — Get vault detail
  • DELETE /vault/:vaultId — Archive vault with a signed summary checkpoint
  • POST /vault/:vaultId/items — Create vault item
  • GET /vault/:vaultId/items — List vault items
  • GET /vault/:vaultId/fields/:fieldId — Get a single field value
  • GET /vault/:vaultId/items/:itemId — Get vault item detail
  • DELETE /vault/:vaultId/items/:itemId — Archive vault item with a signed summary checkpoint

v1.2.0 (January 2026)

• Added POST /domain-manager/dns-records endpoint for adding DNS records

v1.1.0 (January 2026)

• Added GET /project/:id endpoint for project details

v1.0.0 (January 2026)

• Initial release
• Added GET /domain-manager/dns-records endpoint