Authentication and Keys

For the agent password-manager flow, authentication 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 does not have an active registered runtime key for checkpoint signing. 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 or select the agent
5. Copy or regenerate the agent API key

That download gives you only the API key half of the runtime contract. The runtime host must still generate or be provisioned with its own local RSA private key. Security-group access, direct project permissions, and direct vault sharing should be assigned only after the runtime successfully registers its first public key.

For human- or service-backed keys:

• use Platform -> Developer -> API Keys

Generate the Local Private Key

Generate the runtime private key on the host where the agent runs:

openssl genrsa -out ./agent-private-key.pem 2048

Keep this file local to the runtime host. Do not upload it to R4 or commit it to source control.

The CLI and Node SDK derive the matching public key from this private key and register it automatically.

What Happens On First Boot

1. The runtime starts with {accessKey}.{secret} plus its local private key file.
2. The CLI or SDK derives the matching public key.
3. The runtime registers that public key with POST /api/v1/machine/vault/public-key.
4. R4 stores only the public key, fingerprint, and rotation metadata.
5. After that first registration, operators can assign vault-backed access to the agent.
6. 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 the API Key

Recommended Header

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"

Use the CLI for the Full Runtime Contract

The CLI is the shortest path because it handles both the API key and the local private key:

r4 auth login \
  --api-key "$R4_API_KEY" \
  --private-key-path ./agent-private-key.pem
 
r4 auth whoami

Supported environment variables:

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"

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

403 Forbidden / api_key_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 runtime is pointed at the correct project if projectId filtering is enabled
4. the runtime registered its public key before the operator granted that access path

No wrapped key found for this agent and vault

Check:

1. the runtime already completed POST /api/v1/machine/vault/public-key
2. the operator granted security-group, project, or direct access after that first registration
3. if access existed before registration, the operator re-shared or re-assigned it after registration