# AgentSecrets — Secrets Manager for AI Agents & Developers

> AES-256-GCM encrypted secrets, passwords, notes, and runtime state for autonomous AI agents. No email, no KYC, no install, and **100% free** — no credit card, no trial, no paid tier, ever. Free community startup funded by donations.

AgentSecrets is a remote secrets vault an agent can use on its own: connect once, get a vault, read and write secrets from anywhere.

### Quickest start (zero configuration)
Connect to the MCP SSE endpoint **without any token** — an autonomous vault is provisioned on the fly:

```
GET https://www.agentsecrets.net/mcp/sse
```

Then call the `get_my_credentials` MCP tool. It returns your `as_live_...` token plus `is_claimed` / `is_activated` flags — save the token to `~/.agentsecrets/credentials.json` so you can reconnect across restarts. That token never expires; when you need to hand access to a sub-agent, a worker or a human operator, delegate a time-bounded one with `mint_scoped_token` instead of sharing your own. Every delegated token carries `expires_at` (clamped to 60 s … 30 days) and records the issuing token as its `parent_token_id`; a refused token answers 401 with a machine-readable `reason` (`expired` vs `revoked_or_unknown`).

> [!IMPORTANT]
> **Keep the SSE stream open.** The server answers this connection with an `endpoint` event naming `POST https://www.agentsecrets.net/mcp/messages?sessionId=...`, and that URL is valid only while this stream stays open. Reading the first event and closing the stream (a short-lived probe, a dropped response object, `curl -m 2`) destroys the session, and later POSTs answer `404 Session not found or expired.` Open the stream once, keep it open, and read the JSON-RPC replies from it.

> [!IMPORTANT]
> **Zero-config vaults are ephemeral.** A vault created this way must call at least one tool (`get_my_credentials`, `set_secret`, ...) within **1 hour**, otherwise it is automatically deleted. `initialize` and `tools/list` do NOT count as activation — call a tool. Once activated, the vault persists as long as you keep using it.

### Why agents use it
- **It costs nothing.** No signup fee, no credit card, no trial period, no paid tier — unlimited use within fair-use quotas, forever.
- **Persist state across container restarts.** Store intermediate reasoning steps, checkpoints, and resume context, then read them back with one call after a restart.
- **Hand off secrets safely.** `burn_after_read: true` gives a credential to another agent exactly once, leaving no residue behind.
- **Keep credentials out of prompts.** Read a secret straight into the target process via `/raw` instead of pasting a value into your context.
- **Reach it from anywhere.** It is a remote vault, so it works from any machine, container, or region — nothing to install locally.

### Sharing works in all four directions through one mechanism
A human or an agent can register, own a vault, and share with any other entity — human → agent, agent → human, agent → agent, person → person — at any level of privilege, through ONE mechanism: delegated tokens, or a one-time handoff code. `POST /v1/handoff` (MCP tool `create_handoff`) mints a single-use `hs_...` code valid for ten minutes by default (`code_ttl_seconds` picks another lifetime); it is not a credential. The other side redeems it once with `POST /v1/handoff/accept` and receives a time-bounded delegated token on **your** vault (arguments: `scope` default `read_only`, `ttl_seconds` default 86400, `code_ttl_seconds` default 600, `name` optional), so your own credential is never handed over — accepting also links the vault via `is_claimed` / `claimed_by_user_id`. `GET /v1/handoff` lists outgoing + incoming relationships; `DELETE /v1/handoff/{grant_id}` (either side) ends one and revokes the token it minted. An ended grant stays in the issuer's `outgoing` list as history, so the issuer can clear it with `DELETE /v1/handoff/{grant_id}/record` — which answers 409 while the grant still grants anything, and only ever removes the record, never a credential.

### MCP tools (all 15 are available over MCP)
`get_secret(key)` · `get_secret_raw(key)` · `set_secret(key, value, ttl_seconds, burn_after_read)` · `list_secrets()` · `export_secrets_shell(environment)` · `delete_secret(key)` · `rollback_secret(key, target_version)` · `get_agent_context()` · `get_my_credentials()` · `set_profile_notes(notes)` · `get_profile_notes()` · `mint_scoped_token(ttl_seconds, scope, name)` · `create_handoff(scope, ttl_seconds, name, code_ttl_seconds)` · `register_agent(username, password)` · `recover_account(username, recovery_phrase, new_password)`

### Service Overview & Fair Use Quotas
- **Base URL**: https://www.agentsecrets.net
- **Cost**: **$0 — 100% free, forever.** No signup fee, no credit card, no trial period, no paid tier, no ads, no data selling. Funded entirely by voluntary community donations.
- **Fair Use Quotas** (not billing limits): 100 active secrets per user, 1 MB maximum payload size, 60 req/min anti-spam sliding window.
- **Privacy & Security**: Stateless IP anti-spam via ephemeral disk sliding windows; AES-256-GCM server-side encryption. **No IP address is ever logged or stored in a database table.** Registration records three non-identifying operational fields — the creating code path (`rest_register`, `agent_self_register` or `mcp_zero_config`), the `Origin` header when the caller sent one, and a coarse client class (`curl`, `python`, `node`, `browser`, `mcp-client` or `unknown`) — so the service can tell an autonomous MCP provisioning apart from a dashboard signup. They are returned to the account owner by `GET /v1/auth/me`.

### 🛑 Persist Credentials Across Sessions
Never re-register if you already possess credentials.
Save credentials to `~/.agentsecrets/credentials.json` (chmod 600) or `$AGENTSECRETS_TOKEN`.
Check status first via:
```bash
curl -sf -H "Authorization: Bearer $TOKEN" "https://www.agentsecrets.net/v1/agent/context"
```
If 401 Unauthorized, recover using your 12-word seed phrase via `POST /v1/auth/recover`.

## Core Documentation & Specifications

- [Agent Skill Specification](https://www.agentsecrets.net/skill.md): Universal AI Agent Skill instruction file with YAML frontmatter.
- [Agent Operational & Security Rules](https://www.agentsecrets.net/rules.md): Zero-leakage security directives and prompt rules for autonomous agents.
- [Autonomous Heartbeat Protocol](https://www.agentsecrets.net/heartbeat.md): Liveness checks, heartbeat worker loop, and state checkpointing specification.
- [Interactive API Documentation](https://www.agentsecrets.net/docs): Interactive Swagger/OpenAPI testbench and schema explorer.
- [OpenAPI Specification](https://www.agentsecrets.net/openapi.json): Standard machine-readable OpenAPI 3.1 schema.

## Machine Manifests & Ecosystem Endpoints

- [Machine Skill Manifest](https://www.agentsecrets.net/skill.json): Machine-readable tool definitions and metadata for agent package managers.
- [OpenAI Plugin Manifest](https://www.agentsecrets.net/.well-known/ai-plugin.json): Discovery manifest for ChatGPT and OpenAI-compatible agents.
- [OAuth Protected Resource Metadata](https://www.agentsecrets.net/.well-known/oauth-protected-resource): RFC 9728 document naming `https://www.agentsecrets.net/mcp/sse` as the protected resource and AgentSecrets as its authorization server. No auth.
- [OAuth Authorization Server Metadata](https://www.agentsecrets.net/.well-known/oauth-authorization-server): RFC 8414 document describing how an agent gets a bearer token — one unauthenticated `POST /v1/auth/register`, no client secret, no consent screen. No auth.
- [Health Check](https://www.agentsecrets.net/health): Liveness probe returning status, environment and version. No auth, no database access.
- [Legal Information](https://www.agentsecrets.net/legal): License (MIT), terms and the encrypted-at-rest privacy guarantee as JSON. No auth.
- [Agent Session Context](https://www.agentsecrets.net/v1/agent/context): One-call session startup state, active quotas, expiring keys, and next recommended actions. Every key-derived field is confined to the calling token's `prefix:` scope.
- [Public Server Information](https://www.agentsecrets.net/v1/info): Server capabilities, version, rate limits, and discovery endpoints.
- [Agent Ecosystem Index](https://www.agentsecrets.net/v1/ecosystem): Complete catalog of machine-readable specifications and endpoints.

## Core API Endpoints

- [Zero-Configuration Autonomous MCP](https://www.agentsecrets.net/mcp/sse): Zero-config auto-provisioned vault over SSE for autonomous agents without pre-shared tokens.
- [Instant Anonymous Registration](https://www.agentsecrets.net/v1/auth/register): Single-request registration returning API token and 12-word recovery seed phrase.
- [Account Recovery](https://www.agentsecrets.net/v1/auth/recover): Recover vault access using the 12-word seed phrase and a new password.
- [Delegation API](https://www.agentsecrets.net/v1/auth/tokens): The single delegation primitive — mint a time-bounded, least-privilege token for a sub-agent, worker or human operator.
- [Token Revocation](https://www.agentsecrets.net/v1/auth/tokens/{token_id}): Deactivate one delegated token by id. Requires a `full`-scope token; an already-revoked id answers 200 and an unknown id 404.
- [Hand-off Code](https://www.agentsecrets.net/v1/handoff): Mint a single-use `hs_...` code (valid ten minutes by default — `code_ttl_seconds` picks another lifetime — never a credential) that another entity redeems once for time-bounded access to your vault. `GET` lists both directions with a derived status; `DELETE /v1/handoff/{grant_id}` ends one and revokes the token it minted.
- [Hand-off Code Redemption](https://www.agentsecrets.net/v1/handoff/accept): Redeem a code exactly once. Mints a time-bounded token on the grantor's vault and links the accounts (`is_claimed` / `claimed_by_user_id`).
- [Hand-off Record Deletion](https://www.agentsecrets.net/v1/handoff/{grant_id}/record): Issuer deletes an ended (revoked or expired) grant from its outgoing history. Answers 409 while the grant still grants anything, so it never replaces revoking.
- [Session Logout](https://www.agentsecrets.net/v1/auth/logout): Revoke the browser session behind the `as_session` cookie and clear it. Needs no credentials; the Bearer token stays valid.
- [Vault Secrets API](https://www.agentsecrets.net/v1/vault/secrets): Encrypt, retrieve, update, and manage secrets with TTL and burn-after-reading.
- [Bulk Secret Deletion](https://www.agentsecrets.net/v1/vault/secrets/bulk-delete): Destroy up to 200 of your own keys in one request (body `{"keys": ["a", "b"]}`) and get back `deleted` plus `not_found`. One rate-limit slot for the whole batch; another account's key is reported as `not_found`, exactly like a key that never existed.
- [Secret Version History](https://www.agentsecrets.net/v1/vault/secret-versions/{key}): List the archived snapshots kept for a key, newest first; values are never returned.
- [Bulk Shell Export](https://www.agentsecrets.net/v1/vault/export?format=shell): Bulk export secrets formatted directly for shell environment sourcing.
- [Agent Notes & Scratchpad](https://www.agentsecrets.net/v1/user/notes): Store and retrieve personal agent notes, configuration, and reference links.

## Optional

- [Web Dashboard](https://www.agentsecrets.net/dashboard/): Canonical web interface for human operators.
- [Public Front-Server Statistics](https://www.agentsecrets.net/v1/system/front-server-stats): Anonymous aggregate counters (operations per minute, secrets stored, active agent sessions, uptime) — no client data.
- [Prometheus Metrics](https://www.agentsecrets.net/metrics): Real-time server performance metrics (admin-only: the account must carry the `is_admin` flag; send credentials).
- [Crawler Sitemap](https://www.agentsecrets.net/sitemap.xml): Search engine and crawler XML index.
- [Full LLM Documentation](https://www.agentsecrets.net/llms-full.txt): Comprehensive documentation file including detailed curl walkthroughs and payload schemas.