Authentication and Keys

Machine API authentication supports two runtime shapes:

• account profiles, created by r4 login, use a browser-approved device access token
• agent profiles, created from AGENT API credentials, use an API key plus a local runtime private key

For the agent password-manager flow, authentication still means more than “just an API key.”

An agent runtime needs:

• an AGENT-scoped API key
• a local PEM-encoded RSA private key

The API key authenticates the runtime to R4. The private key stays local and is used to unwrap vault DEKs so the runtime can decrypt shared secrets locally.

API Key Format

API keys use this format:

{accessKey}.{secret}

Example:

rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef

Which Scope Should I Use?

If you are giving an autonomous runtime access to passwords and secrets, use an AGENT API key.

Which Permissions Should I Choose?

Machine API keys are created with an endpoint policy as well as a scope.

• Fastest start: machine.all
• Typical AGENT runtime minimum: machine.agent.all, machine.vault.read, machine.vault.secret.read
• Add machine.project.read if the runtime needs project discovery
• Add machine.monitoring.read when the runtime should watch scoped API traffic, audit events, vault activity feeds, or entity counts for read-only monitoring/anomaly detection
• USER, TENANT, and ORG automations can usually start from grouped presets such as machine.vault.all, machine.project.all, machine.domain.all, or machine.billing.all

The key must satisfy both its scope and its machine policy. For example, an AGENT key can still be denied vault-write endpoints if it lacks machine.vault.write or asset access to the target vault or item. Monitoring follows the same rule: AGENT keys can use the scoped metric-stats, entity-counts, request-events, audit-events, and vault-activity-events endpoints, but the infrastructure-only system-stats / session-stats routes still require a global-admin-backed machine key.

Where to Get the API Key

For agent runtimes:

1. Log in to R4
2. Open the authenticated platform dashboard
3. Navigate to Platform -> Developer -> Agents
4. Create the agent, select its security groups, and download the one-time runtime JSON config

When you create a new agent from that platform wizard, R4 generates the runtime key pair locally in the browser, sends only the public key to the backend, creates the AGENT credentials, registers the public key, applies the selected security groups, and offers a one-time JSON download containing agentId, accessKey, accessSecret, and privateKey. If you also save to a vault, the vault item stores only the API credentials, not the private key.

For human- or service-backed keys:

• use Platform -> Developer -> API Keys

Configure Local Profiles

Use the CLI when you want the same local ~/.r4 profile to work from shell commands and the SDK.

Account profile:

r4 login

Agent profile:

r4 configure agent --config ./openclaw-agent-runtime.json

r4 configure agent --config <path> imports the downloaded runtime JSON, verifies the AGENT API credentials, saves the private key under ~/.r4/profiles/<profile>/private-key.pem, and stores the API credentials in that profile's credential file.

Switch profiles with:

r4 profiles
r4 profiles use <profile>
r4 whoami

Downloaded Local Private Key

Keep the downloaded private key local to the runtime host. Do not upload it to R4 or commit it to source control. The Node SDK derives the matching public key from this private key when it needs to validate or rotate runtime encryption state.

What Happens On First Boot

1. The runtime starts with {accessKey}.{secret} plus its local private key file from the one-time platform runtime config.
2. The SDK or runtime derives the matching public key when it verifies local encryption state.
3. R4 already stores the public key, fingerprint, and selected security-group access from agent creation.
4. When vault items are shared to that agent, R4 can deliver wrapped vault DEKs that only that runtime can unwrap locally.

Key Lifecycle Rules

• Re-registering the same public key is idempotent.
• Rotating to a new key requires previousEncryptionKeyId and rotationSignature from the current private key.
• Rotating to a different key while the old key still has active wrapped vault access also requires a client-chosen encryptionKeyId plus a complete rewrappedVaultKeys batch for every active vault DEK.
• If the runtime loses the active private key, normal self-service rotation is blocked because it can no longer produce that rotation proof.
• Plan backup, restore, or reprovisioning around that constraint before you deploy the runtime.

Send Machine Credentials

Agent API Key

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

Alternative Header

curl -H "Authorization: ApiKey $R4_API_KEY" \
  "https://r4.dev/api/v1/machine/vault"

Account Access Token

Account profiles created by r4 login use a CLI device access token. The CLI and SDK send:

curl \
  -H "Authorization: Bearer $R4_ACCESS_TOKEN" \
  -H "x-r4-session-surface: cli" \
  -H "x-r4-device-installation-id: $R4_DEVICE_INSTALLATION_ID" \
  "https://r4.dev/api/v1/machine/me"

Use account access tokens for user-backed CLI/SDK automation. Use AGENT API keys for autonomous runtimes and zero-trust agent secret retrieval.

Account access tokens do not carry a machine permission policy. A device-approved token receives the USER-scope machine permission set minus the access-management write families — machine.org_admin.write, machine.tenant_admin.write, machine.user_manager.write, and machine.permissions.write — and access is then constrained by what that user can actually see and do (tenants, security groups, asset permissions). Automations that need those admin writes, or endpoint-level least privilege in general, should mint a scoped API key with an explicit permission policy instead of reusing a device token.

Legacy Keys Without A Policy

API keys created before endpoint policies existed have no stored grants. They now resolve to the safe default permission bundle for their scope at request time — they no longer receive full access. Calls outside that default bundle return machine_permission_denied. GET /api/v1/machine/me flags these keys with legacyFullAccess: true and a rotation warning; rotate them to pin an explicit policy. New keys always store one, and every scope receives machine.me.read implicitly so a key can always introspect itself.

Default Permission Bundle

Keys created without an explicit policy receive the safe default bundle for their scope: machine.me.read, machine.vault.all, machine.project.all, and machine.domain.all, plus machine.billing.read for USER/TENANT/ORG keys. AGENT keys additionally default to machine.billing.all (the wallet top-up flow), machine.agent.public_key.write, and machine.feedback.all. Billing writes for human-scoped keys must be selected explicitly.

Runtime Environment Variables

Use environment variables or your runtime's secret store for AGENT credentials:

export R4_API_KEY="access_key.secret"
export R4_PRIVATE_KEY_PATH="$PWD/agent-private-key.pem"
export R4_PROJECT_ID="optional-project-id"
export R4_TRUST_STORE_PATH="$PWD/.r4-trust-store.json"

The SDK can also load a profile created by the CLI:

import { R4Client } from '@r4-sdk/node'
 
const client = R4Client.fromProfile({ profile: 'personal' })
const identity = await client.getMachineIdentity()

For R4.create() and local secret decryption, use an agent profile or pass an AGENT API key plus the matching private key.

Security Best Practices

Keep the private key local

• never upload the private key to R4
• never commit it to version control
• never print it in logs

Treat the API key like a secret

• store it in environment variables or a secure runtime config
• rotate it if you suspect compromise
• archive unused keys

Use separate credentials for separate runtimes

• development agent
• staging agent
• production agent

This keeps rotation and revocation safe and targeted.

Troubleshooting

401 Unauthorized

Check:

1. the key is in {accessKey}.{secret} format
2. the key was sent in X-API-Key or Authorization: ApiKey
3. the key has not been archived

For account profiles, check that the bearer token is not expired and that the x-r4-session-surface: cli and device installation headers are present.

403 Forbidden / machine_permission_denied

Check:

1. the key was created with the permission required by that endpoint
2. the selected grouped grant expands to the endpoint you are calling
3. you are not using an AGENT key for a user-backed write path

Public-key registration fails

Check:

1. the runtime is using an AGENT API key
2. the private key file exists and is readable
3. the private key is a valid PEM-encoded RSA key

The runtime lost its private key

Check:

1. whether the original private key is available from your runtime backup or secret-delivery system
2. whether you are only re-registering the same key, which is safe if you still have it
3. whether you need to reprovision a new runtime identity, because normal rotation to a different key requires proof from the current private key

Vault reads succeed but the needed password is missing

Check:

1. the runtime is the expected agent
2. the operator shared the vault item to that agent
3. the field is marked for environment-variable export if you are using r4 project env or R4.create({ projectId })
4. the runtime is pointed at the correct project if projectId filtering is enabled
5. the Platform wizard registered the public key before the operator granted that access path

No wrapped key found for this agent and vault

Check:

1. the agent was created through the Platform wizard and the runtime JSON contains the matching private key
2. the operator granted security-group, project, or direct access after that public key was registered
3. if access existed before registration, the operator re-shared or re-assigned it after registration