# How to Configure Paperclip Secrets Management with Scoped Access per Agent

> Secure your Paperclip secrets with scoped access per agent. Learn how to configure explicit bindings for enhanced security and control over your sensitive data.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: how-to-guide
- Published: 2026-08-18

---

**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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/packages/db/src/schema/company_secrets.ts), [`packages/db/src/schema/company_secret_versions.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/db/src/schema/company_secret_versions.ts), and [`packages/db/src/schema/company_secret_provider_configs.ts`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/cli/src/commands/client/secrets.ts) for operators who prefer terminal workflows.

### Creating a Secret

```bash
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

```bash
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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/agent-secret-bindings.ts) | Core authorization logic for agent-secret access |
| [`server/src/secrets/aws-secrets-manager-provider.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/secrets/aws-secrets-manager-provider.ts) | AWS Secrets Manager provider implementation |
| [`packages/db/src/schema/company_secret_bindings.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/db/src/schema/company_secret_bindings.ts) | Database schema for agent-to-secret mappings |
| [`cli/src/commands/client/secrets.ts`](https://github.com/paperclipai/paperclip/blob/main/cli/src/commands/client/secrets.ts) | CLI interface for secret management |
| [`ui/src/pages/secrets/secret-path.ts`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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.