How to Configure Paperclip Secrets Management with Scoped Access per Agent

Paperclip enforces agent-scoped secret access through explicit bindings stored in the database, where each secret request is validated against the company_secret_bindings table before retrieval from the configured provider.

Paperclip's secrets management system lets you store sensitive credentials like API keys and tokens while restricting which agents can access them. This guide explains how to configure scoped access per agent using Paperclip's three-layer architecture: secret providers, secret definitions, and agent-secret bindings.

Understanding Paperclip's Secrets Architecture

The system rests on three core concepts that work together to isolate and protect sensitive data.

Secret Providers

Secret providers are pluggable back-ends that store actual secret payloads. Paperclip ships with an AWS Secrets Manager provider as the reference implementation.

The provider interface is defined in server/src/secrets/aws-secrets-manager-provider.ts. This file handles the actual retrieval from external secret stores like AWS.

Secret Definitions and Versions

Database schemas in packages/db/src/schema/company_secrets.ts, packages/db/src/schema/company_secret_versions.ts, and packages/db/src/schema/company_secret_provider_configs.ts track each secret's metadata, lifecycle, and provider configuration.

Agent-Secret Bindings

Agent-secret bindings enforce scoped access at runtime. The service server/src/services/agent-secret-bindings.ts contains the core authorization logic that determines whether an agent may read a specific secret. An agent can only retrieve secrets it is explicitly bound to.

How Scoped Access Works at Runtime

When an agent requests a secret, Paperclip validates the request through a four-step flow:

1. Authentication — The agent presents its JWT; the auth layer extracts the agent ID in server/src/routes/secrets.ts.

2. Authorization check — agent-secret-bindings looks up bindings for that agent and validates the requested secret ID.

3. Secret retrieval — If authorized, the secret provider (e.g., AWS) fetches the secret value.

4. Redaction (optional) — UI-side helpers in ui/src/lib/redact-url-secrets.ts strip secret values from URLs before display.

Unauthorized attempts return HTTP 403.

Creating Agent-Secret Bindings

Bindings link specific agents to specific secrets. These records live in the company_secret_bindings table, defined in packages/db/src/schema/company_secret_bindings.ts.

Binding Creation Flow

When you create a secret through the UI or CLI, you specify which agents need access:

• The UI presents a list of available agents
• Selected agents are persisted as binding records
• Only bound agents can subsequently retrieve the secret

This design guarantees explicit opt-in: no agent receives secret access by default.

Enforcing Bindings

Every secret endpoint validates the caller:

• GET /api/secrets/:id
• POST /api/secrets

Each calls agent-secret-bindings to verify the agent ID appears in the binding set.

Auditing Access

All access events are logged to secret_access_events for traceability, as defined in packages/db/src/schema/secret_access_events.ts.

Configuring Secrets via CLI

The CLI provides a secrets command at cli/src/commands/client/secrets.ts for operators who prefer terminal workflows.

Creating a Secret

paperclip secrets create --name my-api-key --provider aws --value <value>

This creates the secret definition and provider configuration in the database.

Binding Agents to a Secret

paperclip secrets bind --secret-id <id> --agents agentA,agentB

This writes binding records to company_secret_bindings, authorizing only agentA and agentB to retrieve this secret.

CLI Configuration

The CLI reads secret-key settings from cli/src/config/secrets-key.ts, which points to the provider configuration stored in the database.

Complete Configuration Example

Here is the full workflow for configuring Paperclip secrets management with scoped access per agent:

1. Create the secret using the CLI or UI at ui/src/pages/secrets/secret-path.ts.

2. Select agents during creation; these bindings persist to company_secret_bindings.

3. Agent requests the secret through GET /api/secrets/:id.

4. Validation occurs — agent-secret-bindings.ts checks the agent ID against the binding table.

5. Authorized retrieval — the AWS provider fetches the value only for valid requests.

Key Implementation Files

File	Purpose
server/src/services/agent-secret-bindings.ts	Core authorization logic for agent-secret access
server/src/secrets/aws-secrets-manager-provider.ts	AWS Secrets Manager provider implementation
packages/db/src/schema/company_secret_bindings.ts	Database schema for agent-to-secret mappings
cli/src/commands/client/secrets.ts	CLI interface for secret management
ui/src/pages/secrets/secret-path.ts	Frontend route for secret details with binding awareness

Summary

• Paperclip secrets use provider plugins for external storage, database schemas for metadata, and explicit bindings for access control.
• The agent-secret-bindings.ts service is the enforcement point for all secret access.
• Scoped access per agent requires creating bindings in company_secret_bindings — no implicit access exists.
• CLI commands secrets create and secrets bind automate the configuration workflow.
• All access is auditable through secret_access_events.

Frequently Asked Questions

How does Paperclip prevent unauthorized agents from accessing secrets?

Every secret request routes through agent-secret-bindings.ts, which queries the company_secret_bindings table. If the requesting agent's ID is not found in the binding set for that secret, the service returns HTTP 403 and blocks retrieval. This check occurs before any provider call, ensuring secrets never leak to unbound agents.

Can I use a secret provider other than AWS Secrets Manager?

Yes. The provider architecture in server/src/secrets/ is pluggable. You can implement the same interface as aws-secrets-manager-provider.ts for HashiCorp Vault, Azure Key Vault, or any custom back-end. The secret definition in company_secrets stores which provider handles each secret.

What happens if I don't bind any agents to a secret?

The secret becomes unreadable by all agents. Since Paperclip's scoped access model requires explicit bindings, a secret with zero bindings cannot be retrieved through the API. This is a security feature — secrets are inaccessible by default until you deliberately grant access.

Is there a way to audit which agents accessed which secrets?

Yes. Schema secret_access_events.ts defines the audit table that logs every successful secret access. Each record includes the agent ID, secret ID, timestamp, and request context. Query this table to generate compliance reports or investigate suspicious access patterns.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}