KeySlip / SurCod
Back to KeySlip

AGENT FRIENDLY / DEVELOPER GUIDE

Integrate. Encrypt. Share.

One-time sharing for applications, scripts and agents. The server receives ciphertext, not your message.

01 / API · CLI · MCP

Choose where you want to integrate.

Use the HTTP API in your application, the CLI in scripts, or the local MCP server in an agent. There is no endpoint that accepts plaintext.

llms.txt ↗

02 / HTTP API

Send ciphertext. Keep the key.

Encrypt in your client before making the request. The response gives you an ID; build the share link locally with the key after #.

POST/api/secrets201
{
  "ct": "<base64url ciphertext + authentication tag>",
  "iv": "<base64url 12-byte IV>",
  "sare": null,
  "expira": 3600
}

Illustrative wire format. Generate ciphertext and fresh random values in your client; do not send these placeholders.

POST/api/secrets/{id}/read200 / 404

No request body. Returns encrypted content and consumes the message atomically. Decrypt locally with the key from the link. A second read returns 404.

A read is destructive. Never retry it automatically, including after a network timeout.

A client example

import { send } from "./client.mjs";

const link = await send(
  "https://keyslip.app",
  "A fictional demo message",
  3600
);
console.log(link);
Get the JavaScript client ↗
03 / CLI

The same protection, from your terminal.

Download the CLI & MCP client

Choose your operating system and CPU. Extract the archive, verify its SHA-256 checksum and use the same executable for CLI and MCP.

A terminal handoff can use stdin.

Need to pass a generated credential to a teammate? KeySlip’s CLI guide shows how to send a single-read message from a terminal. The example uses fictional text. The send command reads the message from standard input, so a real secret can come from a trusted source without being typed into a shell command. The process or environment supplying that input may still record it, so use a trusted environment.

After a successful send, the sender gets a link. Share the complete link privately with the intended recipient; it contains the decryption key in its fragment. The first read request may consume the message even if the response is lost or the connection is interrupted. Do not automatically retry the read request.

Read the terminal guide and try KeySlip’s free flow at keyslip.app.

# Extract your platform download first.
# On macOS/Linux: chmod +x keyslip

# Use fictional content for this example
printf '%s' 'A fictional demo message' | \
  ./keyslip send --expire 1h

# Read explicitly, once; $link holds the full share link
./keyslip read "$link"

Optional password input is supported via --password-stdin. Keep the password separate from the share link.

04 / MCP · STDIO

Give your agent a local tool.

Install an MCP bundle

For clients that support MCPB, download the bundle matching your operating system and CPU. Verify its checksum before installation. Other clients can use the executable configuration below.

Run the MCP process on your machine. It exposes send_secret and read_secret over stdio, without opening a network port.

{
  "mcpServers": {
    "keyslip": {
      "command": "/absolute/path/to/keyslip",
      "args": ["mcp"],
      "env": { "KEYSLIP_SERVER": "https://keyslip.app" }
    }
  }
}
send_secretEncrypt locally → return a share link
read_secretConsume once → decrypt locally

The agent and local MCP process can see the plaintext. Read only with the recipient’s agreement; the read tool is destructive and non-idempotent.

05 / CONTRACT

Predictable limits and errors.

Expiry
10m · 1h · 1d · 7d
Client message size
32,000 UTF-8 bytes
Hourly attempts per client
30 create · 60 read
HTTP
400 · 404 · 413 · 415 · 429 · 500

429 includes Retry-After. Errors use a JSON object with a mesaj field. An expired or consumed secret returns 404.

Full wire format, crypto parameters and Python examples ↗