secure-api-calls

Call any API without leaking credentials. Keychains proxies requests and injects real tokens server-side — your agent never sees them.

# Secure API Calls with Keychains

[keychains.dev](https://keychains.dev) is a credential proxy for AI agents. Instead of real API keys and OAuth tokens, you use **placeholders** like `{{OAUTH2_ACCESS_TOKEN}}`. Keychains injects the real credentials server-side — your agent never sees them.

## Quick Start

### Install:
```
npm install -g keychains@0.0.13
```

### Basic usage:
```
keychains curl https://api.github.com/user/repos \
  -H "Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}"
```

## Examples

- "List GitHub repos: `keychains curl https://api.github.com/user/repos -H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}'`"
- "Send Slack message: `keychains curl https://slack.com/api/chat.postMessage -X POST -H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' -H 'Content-Type: application/json' -d '{\"channel\":\"#general\",\"text\":\"Hello!\"}'`"
- "List Stripe customers: `keychains curl https://api.stripe.com/v1/customers?limit=5 -H 'Authorization: Bearer {{STRIPE_SECRET_KEY}}'`"
- "Read Gmail: `keychains curl 'https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=10' -H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}'`"

## How It Works

1. Use `keychains curl` instead of `curl`. Put `{{PLACEHOLDER}}` where the credential goes.
2. First time, keychains returns an **approval link** instead of the API response.
3. Show the link to the user. They approve via FaceID/Passkey and connect their account.
4. Replay the command — it works. All future requests to that provider succeed instantly.

No credentials ever pass through the agent. The user controls everything from [keychains.dev/dashboard](https://keychains.dev/dashboard).

## Setup Requirements

- **Node.js** (v16+) — needed for `npm install -g keychains@0.0.13`
- No API keys or environment variables needed
- Machine registration is automatic on first run (creates `~/.keychains/` with an Ed25519 SSH keypair)

## Template Variables

Put `{{VARIABLE_NAME}}` where you'd normally put the real credential — in headers, body, or query params.

| Prefix | Type | Examples |
|--------|------|----------|
| `OAUTH2_` | OAuth 2.0 | `{{OAUTH2_ACCESS_TOKEN}}`, `{{OAUTH2_REFRESH_TOKEN}}` |
| `OAUTH1_` | OAuth 1.0 | `{{OAUTH1_ACCESS_TOKEN}}`, `{{OAUTH1_REFRESH_TOKEN}}` |
| Anything else | API key | `{{STRIPE_SECRET_KEY}}`, `{{OPENAI_API_KEY}}` |

Keychains auto-detects the provider from the URL.

## Waiting for User Approval

When keychains returns an approval link, show it to the user and poll:

```bash
keychains curl https://api.github.com/user/repos \
  -H "Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}"
# → "Authorize at: https://keychains.dev/approve/abc123xyz"

keychains wait https://keychains.dev/approve/abc123xyz --timeout 800

keychains curl https://api.github.com/user/repos \
  -H "Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}"
# → works now
```

## TypeScript Machine SDK

For TypeScript/Node.js agents, `@keychains/machine-sdk` provides `keychainsFetch()` — a drop-in `fetch()` replacement with the same automatic registration and credential handling as the CLI.

```
npm install @keychains/machine-sdk
```

```typescript
import { keychainsFetch, KeychainsError } from '@keychains/machine-sdk';

try {
  const res = await keychainsFetch('https://api.github.com/user/repos', {
    headers: { Authorization: 'Bearer {{OAUTH2_ACCESS_TOKEN}}' },
  });
  console.log(await res.json());
} catch (err) {
  if (err instanceof KeychainsError && err.approvalUrl) {
    console.log('Please approve:', err.approvalUrl);
  }
}
```

## Other Available SDKs

| SDK | Install | Description |
|-----|---------|-------------|
| [Python SDK](https://pypi.org/project/keychains/) | `pip install keychains` | Drop-in `requests` replacement. `keychains.get()`, `keychains.post()`, `keychains.Session()`. |
| [Client SDK](https://www.npmjs.com/package/@keychains/client-sdk) | `npm install @keychains/client-sdk` | TypeScript SDK for delegated environments (VMs, cloud functions). |

## Security & Data Flow

Full details: [security whitepaper](https://keychains.dev/api/whitepaper) · [privacy policy](https://keychains.dev/privacy) · [terms of service](https://keychains.dev/terms)

**How proxying works:** Your request (URL, headers, body) is routed through keychains.dev. The proxy replaces `{{PLACEHOLDER}}` variables with real credentials from the user's vault, forwards to the upstream API, and returns the response as-is. The proxy does **not** store or modify the response body.

**Credential encryption:** AES-256-GCM at rest. Only decrypted in memory at proxy time. Auto-deleted 90 days after last use. Never sold or shared.

**Audit log:** Every proxied request is logged (URL, method, provider, timestamp, status code). Archived to AWS S3 with Object Lock — immutable, tamper-proof. Configurable retention (30 days–3 years). Request/response bodies and credential values are **never** logged.

**Local keys:** On first run, an Ed25519 SSH keypair is generated in `~/.keychains/` (private key: 0600 permissions, never leaves the machine). Used for machine auth via SSH challenge-response. Rotate anytime with `keychains machine rotate-keys`.

**Credential isolation:** Real credentials live only in the user's vault on keychains.dev. Never sent to the agent. Bound to their provider (a GitHub token can only go to github.com).

**Infrastructure:** Vercel (app), Upstash Redis (ephemeral state), MongoDB Atlas (persistent, encrypted), AWS S3 (audit archival). All under data processing agreements.

**User control:** Biometric approval required for every credential use. Instant revocation per machine, provider, or agent. Full data export (JSON), account deletion, GDPR/CCPA compliant. No tracking, no ads, no data sales.

## Troubleshooting

**Got an approval link?** Normal. Show it to the user, wait for approval, retry.

**Template variable not replaced?** You're using regular `curl`/`fetch` instead of `keychains curl` / `keychainsFetch()`.

## Resources

- [keychains.dev](https://keychains.dev) — Website & docs
- [keychains.dev/dashboard](https://keychains.dev/dashboard) — Dashboard & audit trail
- [github.com/interagentic/keychains.dev_skill](https://github.com/interagentic/keychains.dev_skill) — Source code

---

## Compatible with 5545+ Providers (and counting)

Tested with the following providers so far:

- &Open Gifts (andopen.co)
- 0CodeKit (0codekit.com)
- 100Hires ATS (100hires.com)
- 10xcrm (10xcrm.com)
- 123FormBuilder (123formbuilder.com)
- 17hats (17hats.com)
- 1ClickImpact (1clickimpact.com)
- 1crm (1crm.com)
- 1st things 1st (1st-things-1st.com)
- 21risk (21risk.com)
- 2Chat (2chat.co)
- 360dialog (360dialog.com)
- 360Score.me (360score.me)
- 3C Connect (3cconnect.com)
- 3sigmacrm (3sigmacrm.com)
- 3veta (3veta.com)
- 4.events (4.events)
- 46elks (46elks.com)
- 4aGoodCause (4agoodcause.com)
- 4DEM (4dem.it)
- 4HSE (4hse.com)
- 4Pay (4pay.online)
- 5 Stars Reputation (5starsreputation.net.au)
- 6clicks (6clicks.io)
- 6ix (6ix.com)
- 7Targets (solution.7targets.com)
- 8x8 (8x8.com)
- 99designs (99designs.com)
- A1WebStats (websuccessinsights.com)
- aamarPay (aamarpay.com)
- AB.GL (abgl.link)
- Abby Connect (abby.com)
- ABC Sales AI (abcsales.ai)
- ablefy (ablefy.io)
- about (about.motimateapp.com)
- Abstract (abstractapi.com)
- abyssale (abyssale.com)
- academia (academia.clientify.com)
- academyocean (academyocean.com)
- Acadimiat (acadimiat.com)
- Accelo (accelo.com)
- Access Charity Websites (theaccessgroup.com)
- accessally (accessally.com)
- Accompa (accompa.com)
- Accord (inaccord.com)
- AccountEdge (accountedge.com)
- AccountGroove (accountgroove.com)
- Accredible (accredible.com)
- AccuWeather (accuweather.com)
- Acquia (acquia.com)
- Acquire (acquire.io)
- Acrual (acrual.com)
- Act-On (act-on.com)
- Act! (act.com)
- Action Network (actionnetwork.org)
- Action1 (action1.com)
- Actionstep (actionstep.com)
- Active Knocker (activeknocker.com)
- ActiveCalculator (activecalculator.com)
- ActiveCampaign (activecampaign.com)
- activecollab (act