Passwordn Developer Docs

Quick start

Passwordn is a zero-knowledge credential vault built for agencies. All encryption happens in your browser — we never see your master password or decrypted data.

1. Open the vault app and create a master password (12+ characters recommended).
2. Create your first client — a named group for one business you manage.
3. Add credentials from the Service Catalog or manually via New Login.
4. Install the Chrome extension for one-click autofill on any site.

Creating a vault

On first open, Passwordn creates an encrypted vault in your browser's localStorage. The vault is a JSON blob encrypted with AES-256-GCM using a key derived from your master password.

Your vault is portable — use the export function to download it as an encrypted .pn file and import it on any device.

Master password

Your master password is the single key to your vault. It is never transmitted to any server. We derive your encryption key using PBKDF2-SHA256 at 600,000 iterations — matching OWASP's current recommendation for key derivation.

There is no password reset. If you lose your master password, your vault data cannot be recovered. Write it down in a secure offline location.

Clients & groups

A client is a named group that owns a set of credentials. Every login in your vault is assigned to a client (or kept as "Personal"). This lets you switch contexts instantly — see only Harbor Digital's accounts, or only Acme Corp's.

Creating a client

Go to Clients in the sidebar → click New client. Fill in the name, website, brand color, and optional plan/tier label. The color is used for the avatar icon across the vault.

Filtering by client

From the Clients grid, click View logins on any card to switch to the Logins view pre-filtered to that client. You can also click anywhere on the client card. Clear the filter by returning to the Clients view.

Credentials

Each credential stores a name, URL, username/email, and password. Passwords are scored using real entropy (not a superficial pattern check) and flagged when weak (<50 bits) or stale (>60 days).

Quick-add from the catalog

Open Service Catalog, find the service (e.g. Webflow, GitHub, n8n), and click its tile. A New Login modal pre-fills the service name and URL — just enter the username and password.

Subscriptions

The Subscriptions view tracks recurring charges. Each subscription has a name, monthly cost, category, and next renewal date. The summary cards show total monthly spend, upcoming renewals, and annual projection.

Importing a bank statement

Click Import statement and upload a CSV export from your bank or credit card. Passwordn will scan for recurring merchant names and suggest subscriptions to add. Statement data is processed locally and never uploaded.

Cancelling a subscription

Click Manage on any row to open the service's billing page directly (for services in the catalog). Click Cancel to remove it from tracking.

Service catalog

The built-in catalog includes 60+ services pre-configured with brand colors, login URLs, billing management URLs, and default subscription prices. Categories include Automation, AI, Dev, Website, Hosting, Design, Comms, Email, Social, Finance, Analytics, and Security.

Services are defined in js/services.js. You can fork this file to add internal tools or custom services.

Extension installation

The Chrome extension is not yet in the Chrome Web Store (review pending). Load it as an unpacked extension:

1. Download passwordn-extension.zip and unzip it.
2. Open chrome://extensions, enable Developer mode.
3. Click Load unpacked and select the unzipped folder.
4. Pin the Passwordn icon and open it to connect to your vault.

Supported browsers: Chrome 109+, Brave, Edge, Arc.

Autofill

The extension attaches an Autofill badge to password fields on any page. Click it to see matching credentials from your vault — filtered by the current domain.

Keyboard shortcut: ⌘⇧L (Mac) / Ctrl+Shift+L (Windows) fills without opening the popup.

Domain matching is strict — stripe.com credentials will never autofill into str1pe.com. Matching is performed locally, before any network request.

Credential capture

When you submit a login or sign-up form with new credentials, the extension detects the submission and offers to save them. You always see a confirmation prompt — nothing is saved without your explicit approval.

If a credential for that domain already exists, the extension will offer to update the password instead.

API authentication

The Passwordn REST API uses bearer token authentication. Generate an API key from Settings → API keys in the vault app (Agency and Enterprise plans).

# All API requests require this header
Authorization: Bearer pn_live_your_api_key_here

API keys are scoped: read, write, or admin. Use the minimum scope required. Keys are displayed only once — store them in your own secure vault.

Clients API

# Example: list clients
curl https://api.passwordn.app/v1/clients \
  -H "Authorization: Bearer pn_live_..."

# Response
{
  "clients": [
    { "id": "cl_abc123", "name": "Acme Corp", "url": "acmecorp.com",
      "credential_count": 12, "status": "active" }
  ]
}

Credentials API

# Get credentials for a client
curl https://api.passwordn.app/v1/clients/cl_abc123/credentials \
  -H "Authorization: Bearer pn_live_..."

# Returns masked data by default (password is not included)
{
  "credentials": [
    { "id": "cr_xyz", "name": "GitHub", "url": "github.com",
      "username": "acme@company.com", "password": null }
  ]
}

MCP overview

Passwordn exposes a Model Context Protocol server so AI agents — Claude, n8n AI nodes, or any MCP-compatible client — can request credentials without the credentials ever appearing in plaintext in prompts or logs.

The MCP server acts as a secure intermediary: the agent asks for a credential by name, and the server returns it directly to the target application without exposing it to the language model's context window.

MCP setup

Add Passwordn to your Claude Desktop or MCP-compatible tool:

# claude_desktop_config.json
{
  "mcpServers": {
    "passwordn": {
      "command": "npx",
      "args": ["@passwordn/mcp-server"],
      "env": {
        "PASSWORDN_API_KEY": "pn_live_your_key",
        "PASSWORDN_VAULT_ID": "your_vault_id"
      }
    }
  }
}

Or use the hosted endpoint — no local install required (Agency and Enterprise plans):

"url": "https://mcp.passwordn.app/v1",
"headers": { "Authorization": "Bearer pn_live_..." }

MCP tools

Once connected, the following tools are available to your AI agent:

# Example agent prompt using Passwordn MCP
"Log into Acme Corp's Squarespace account and update
the homepage hero image. Use their credentials from
my Passwordn vault."

# Claude calls: get_credential(client_name="Acme Corp",
#                              service_name="Squarespace")
# Returns credentials directly to the tool — never to the prompt

Encryption model

Passwordn uses a layered encryption approach:

1. Key derivation — PBKDF2-SHA256, 600,000 iterations, 16-byte random salt. The derived key is 256 bits.
2. Vault encryption — AES-256-GCM with a 96-bit random IV per encryption operation. The GCM tag authenticates the ciphertext, preventing silent tampering.
3. Auth check — A separate small payload is encrypted with the same key; decrypting it validates the password before attempting to decrypt the full vault blob.
4. Session key — The derived key exists only in memory during the session. On lock or tab close, the key is discarded.

// Vault schema (stored in localStorage)
{
  "v": 1,                          // schema version
  "salt": "base64...",             // 16-byte PBKDF2 salt
  "iters": 600000,               // PBKDF2 iterations
  "auth": { "iv": "...", "ct": "..." },  // auth check blob
  "blob": { "iv": "...", "ct": "..." }   // encrypted vault data
}

Zero-knowledge architecture

Passwordn is zero-knowledge: the server stores only ciphertext. We cannot decrypt your vault. Here is what we do and don't see:

This means we cannot help you recover a lost master password. It also means a breach of our servers exposes nothing — an attacker would need your master password plus the ciphertext to decrypt anything.