# Security overview

[Download Security Whitepaper (PDF)](/content/api/whitepaper/index.html)

# Your agent gets the access.  Never the keys.

Keychains is designed so that even if an agent is fully compromised, user credentials remain safe. Here's how.

## The threat model we design for

We assume the worst: agents can be manipulated, context windows can leak, and private keys can be stolen. Keychains is built to keep credentials safe even in these scenarios.

- **Prompt injection**
- **SSH private key theft**
- **Invisible credential usage**
- **Privilege escalation**
- **Credential redirection**

### Prompt injection

1 of 5

**Attack**  
A malicious tool or user input manipulates the agent into exfiltrating credentials from its context.

**Defense**  
Credentials never enter the agent's context. They're injected server-side by the proxy.

## SSH-based machine identity

Every machine that interacts with Keychains is identified by an SSH keypair — the same battle-tested cryptographic primitive that secures servers worldwide.

- **Ed25519 keypairs**  
Modern elliptic curve cryptography. Fast, small, and highly secure.
- **Private key stays local**  
Only the public key is registered with Keychains. The private key never leaves the machine.
- **No credentials in agent environment**  
Your agent authenticates with an SSH keypair — not with shared API credentials. Raw secrets never enter the agent's environment.

#### Why SSH over JWT?

JWTs are bearer tokens — anyone who has the token can use it. SSH keypairs use challenge-response authentication: the server sends a challenge, and only the holder of the private key can sign it. Even if network traffic is intercepted, the private key remains safe.

#### Key rotation

Machines can rotate their keypairs at any time. The old key is invalidated immediately, and the new public key is registered. No downtime, no token refresh races.

## Stateful fingerprinting

SSH keypairs alone aren't enough. If an attacker copies the private key, they could impersonate the machine. That's why Keychains adds a stateful fingerprinting layer.

Each successful authentication advances a cryptographic hash chain shared between the client and server. The state ratchets forward with every call. If an attacker uses a stolen key, the states diverge — and both the attacker's and real machine's next call triggers detection and immediate key invalidation.

#### How fingerprint verification works

1. Machine sends signed request + current fingerprint state
2. Server verifies signature + compares fingerprint against stored state
3. If match: request proceeds, state advances  
   ! If mismatch: key immediately invalidated, user notified

## Credential isolation & data flow

### How credentials flow

The most important security property: credentials never enter the agent's environment. Agents only manipulate credential variable names like `{{OAUTH2_ACCESS_TOKEN}}`. The real secrets are stored and managed exclusively by keychains.dev.

### Two proxy modes

Choose where API traffic flows. Both modes share the same credential isolation model — the difference is where the proxy runs and what data passes through our servers.

- **Managed proxy**  
  Everything flows through keychains.dev. Simplest setup — zero configuration. Credentials are resolved and injected server-side.
- **Satellite proxy**  
  Your agent makes requests directly using their resolved secrets without passing through keychains.dev.

## User sovereignty

### Informed consent

Users see exactly what each agent is requesting — which APIs, which scopes, for what purpose — before granting access.

### Continuous visibility

The dashboard shows all active permissions, which agents hold them, and a complete history of API calls made with user credentials.

### Instant revocation

One click revokes any machine's access. No grace periods, no token TTL to wait out. The proxy rejects the next call immediately.

## Trust boundary

Transparency about where credentials exist is as important as protecting them. Here's exactly what lives where.

### Where credentials exist

- Encrypted at rest in the credential store (AES-256-GCM)
- Decrypted in memory during the proxy request (server-side)
- Injected into the outgoing HTTP request to the target API

### What the agent sees

- The API response (may contain sensitive data, but not credentials)
- A permission token — contains no secrets, expires in 5-15 minutes, and is scoped exclusively to the credentials the user authorized for this specific permission

### Technical deep dive

**Read the Security Whitepaper**  
Our whitepaper covers the full STRIDE threat model, cryptographic primitives, trust boundaries, known limitations, and compliance posture in detail.

[Download Whitepaper (PDF)](/content/api/whitepaper/index.html)

## Trust is earned, not assumed.