Browse docs+

Permission Management

Use this guide when a machine caller needs to inspect or replace direct permissions for projects, vaults, vault items, or other permission-managed assets.

The machine API already supports these flows. The missing piece was public documentation coverage.

Requirements

machine.permissions.read / machine.permissions.write
ADMIN access to the target asset
for agent-led orchestration, the parent runtime usually also needs TENANT_AGENT_MANAGER plus machine.agent.* so it can create or manage the child agent first

Supported Asset Types

The machine permissions routes accept these assetType values today:

PROJECT
VAULT
VAULT_ITEM
LICENSE_INSTANCE
ENCRYPTION_KEY

Project, vault, and vault-item permissions are the most common automation cases and are the focus of this guide.

Core Permission Routes

Endpoint	Method	Purpose
`/api/v1/machine/permissions/:id/access`	`GET`	Inspect the current caller's effective access to one asset
`/api/v1/machine/permissions/:assetType/warning-message`	`GET`	Read asset-type-specific permission caveats
`/api/v1/machine/permissions/security-groups`	`GET`	List tenant security groups you can assign
`/api/v1/machine/permissions/tenant-members`	`GET`	List tenant members you can assign
`/api/v1/machine/permissions/projects`	`GET`	List projects for permission targets
`/api/v1/machine/permissions/agents`	`GET`	List agents for permission targets
`/api/v1/machine/permissions/:assetType/:id/permissions`	`GET`	Read the direct permission rows for one asset
`/api/v1/machine/permissions/:assetType/:id/resolved-access`	`GET`	Read effective access including inherited sources
`/api/v1/machine/permissions/:assetType/:id/set-permissions`	`POST`	Replace the direct permission rows for one asset

Request Body For `set-permissions`

Field	Type	Required	Description
`permissions`	array	Yes	Complete replacement list of direct permission rows
`emailAlert`	boolean	No	Whether to send an email alert for the share change
`permissionCheckpoint`	object	No for `PROJECT`, Yes for `VAULT` and `VAULT_ITEM`	Signed direct-permissions checkpoint

Each permission entry uses:

Field	Type	Required	Description
`id`	string	Yes	Target entity ID
`name`	string	Yes	Display name
`type`	string	Yes	One of `user`, `securityGroup`, `project`, or `agent`
`avatar`	number \| null	No	Optional avatar identifier
`isDefault`	boolean \| null	No	Optional default-group flag
`access`	string	Yes	`READ`, `WRITE`, or `ADMIN`

set-permissions replaces the full direct-permission list. Include every row you want to keep.

Project Permissions

Projects are the simplest delegated-access flow because they do not require a permission checkpoint.

curl -X POST "https://r4.dev/api/v1/machine/permissions/PROJECT/PROJECT_ID/set-permissions" \
  -H "X-API-Key: YOUR_MACHINE_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"
      }
    ],
    "emailAlert": false
  }'

Inspect the current direct rows:

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

Inspect effective access, including inherited sources:

curl "https://r4.dev/api/v1/machine/permissions/PROJECT/PROJECT_ID/resolved-access" \
  -H "X-API-Key: YOUR_MACHINE_KEY"

Vault Permissions

Vault permission changes are checkpoint-backed zero-trust writes.

For assetType: "VAULT":

permissionCheckpoint is required
the checkpoint signer must be an active user key owned by the caller
the checkpoint version must be the next stored direct-permissions version
the checkpoint permission list must exactly match the submitted permissions body

curl -X POST "https://r4.dev/api/v1/machine/permissions/VAULT/VAULT_ID/set-permissions" \
  -H "X-API-Key: YOUR_MACHINE_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"
    }
  }'

Vault-Item Permissions

Vault-item permissions use the same route pattern and the same checkpoint requirement as vault permissions:

POST /api/v1/machine/permissions/VAULT_ITEM/:id/set-permissions

Important caveat:

all users with access to the parent vault still have access to the vault item, regardless of the vault-item-specific direct permission rows

You can read that caveat programmatically through:

curl "https://r4.dev/api/v1/machine/permissions/VAULT_ITEM/warning-message" \
  -H "X-API-Key: YOUR_MACHINE_KEY"

Example vault-item permission update:

curl -X POST "https://r4.dev/api/v1/machine/permissions/VAULT_ITEM/VAULT_ITEM_ID/set-permissions" \
  -H "X-API-Key: YOUR_MACHINE_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"
    }
  }'

Unlike other asset types, VAULT_ITEM direct permissions can be set to an empty array when you need to remove item-only direct grants and rely only on inherited parent-vault access.

Helper Selectors

These helper endpoints are useful when your runtime needs to build or validate a new permission set before calling set-permissions:

GET /api/v1/machine/permissions/security-groups
GET /api/v1/machine/permissions/tenant-members
GET /api/v1/machine/permissions/projects
GET /api/v1/machine/permissions/agents

Recommended Orchestration Order

create or identify the child agent
confirm the target asset ID
inspect current direct permissions or resolved access
build the full replacement permission list
for vault or vault-item changes, build and sign the matching permissionCheckpoint
submit set-permissions

For agent creation and lifecycle operations, see Agent Orchestration.