Credential Vault and Auth Framework for AI Agents

0.8.2 verified Wed Apr 22 auth: no javascript

agent.pw is a robust credential vault and authentication framework specifically designed for AI agents. It provides secure storage for encrypted credentials, including OAuth tokens and API keys, utilizing AES-GCM for data at rest. The library manages the entire OAuth lifecycle, supporting PKCE, token refresh, revocation, and RFC 9728 discovery. Currently at version 0.8.2, the project exhibits a rapid release cadence with frequent patch and minor updates (multiple in April 2026 alone), indicating active development and continuous improvement. Key differentiators include its agent-centric design, comprehensive OAuth handling, support for admin-configurable credential profiles, path-based organization (`ltree` paths like `acme.connections.github`), and scoped access control. It is designed to be embeddable, working seamlessly with any PostgreSQL-compatible database without requiring a separate server component.

Common errors

error Error: DATABASE_URL environment variable is required. ↓

cause The `DATABASE_URL` environment variable was not set or was empty when `createDb` was called.

fix

Set the DATABASE_URL environment variable in your environment (e.g., .env file, shell export) to a valid PostgreSQL connection string before running your application.

error Error: AGENTPW_ENCRYPTION_KEY environment variable is required. ↓

cause The `AGENTPW_ENCRYPTION_KEY` environment variable was not set or was empty during `createAgentPw` initialization.

fix

Provide a secure, randomly generated string for the AGENTPW_ENCRYPTION_KEY environment variable. This key is used to encrypt all stored credentials.

error OAuthError: Invalid redirect_uri ↓

cause The `redirectUri` passed to `agentPw.connect.startOAuth` does not match the URI registered with the OAuth provider.

fix

Double-check the redirectUri parameter against your OAuth application's configuration on the provider's side and ensure they are an exact match, including protocol, hostname, port, and path.

error Error: Unwrapped an Err value. Original error: [Some specific database error] ↓

cause An operation on the database (e.g., connection, query) failed, and the `unwrap` call on the `Result` type threw an error.

fix

Inspect the 'Original error' message for specifics. This usually indicates an issue with the DATABASE_URL, network connectivity to the database, or database permissions. Ensure your database is running and accessible.

Warnings

breaking As `agent.pw` is in active `0.x.x` development, minor version increments (e.g., `0.6.0` to `0.7.0`) may introduce breaking API changes not explicitly detailed as such. Always review release notes carefully when upgrading. ↓

fix Consult the GitHub release notes and commit history for specific changes between minor versions. Update your API calls and configurations accordingly.

gotcha The `encryptionKey` is critical for credential security. Losing this key will result in irreversible loss of access to all encrypted credentials stored by `agent.pw`. It must be a strong, securely generated secret. ↓

fix Ensure the `AGENTPW_ENCRYPTION_KEY` environment variable is set with a robust, persistent secret, ideally managed by a dedicated secrets management system. Never hardcode or expose it directly in source control.

gotcha Many `agent.pw` operations return `Result` types (an `Ok` or `Err` wrapper) requiring the use of `unwrap` from `okay-error`. Failing to handle potential errors from `unwrap` can lead to uncaught exceptions and application crashes. ↓

fix Always wrap `unwrap` calls in `try...catch` blocks or use explicit error handling patterns like `if (result.isErr()) { ... }` when dealing with `Result` types to gracefully manage failures.

breaking Version `0.8.0` introduced the ability to initialize with a profile-only configuration without an encryption key, but the core `createAgentPw` function still mandates an `encryptionKey` if you intend to store secrets. This feature primarily applies to specific `connect.prepare` flows. ↓

fix For full credential management capabilities, always provide a valid `encryptionKey` to `createAgentPw`. If you're leveraging profile-only initialization, ensure your use case aligns with the specific capabilities enabled by this feature.

gotcha The OAuth redirect URIs (`redirectUri`) specified in `agentPw.connect.startOAuth` must exactly match the redirect URIs configured with the OAuth provider. Mismatches will result in authorization failures. ↓

fix Carefully verify and synchronize the `redirectUri` used in your `startOAuth` call with the settings in the third-party OAuth provider's application configuration.

Install

npm install agent.pw

yarn add agent.pw

pnpm add agent.pw

Imports

createAgentPw
wrong
```
const { createAgentPw } = require('agent.pw');
```
correct
```
import { createAgentPw } from 'agent.pw';
```
agent.pw is primarily an ESM module, though CJS usage might be possible via transpilation or specific Node.js settings, ESM is recommended.
createInMemoryFlowStore
wrong
```
import { createInMemoryFlowStore } from 'agent.pw';
```
correct
```
import { createInMemoryFlowStore } from 'agent.pw/oauth';
```
OAuth-related utilities are located in the 'agent.pw/oauth' subpath. Ensure correct subpath import for specific features.
createDb
wrong
```
import { createDb } from 'agent.pw';
```
correct
```
import { createDb } from 'agent.pw/sql';
```
Database connection utilities are located in the 'agent.pw/sql' subpath. This is a common mistake to import from the root.
unwrap
wrong
```
import { unwrap } from 'agent.pw';
```
correct
```
import { unwrap } from 'okay-error';
```
The `unwrap` utility is an external dependency from the `okay-error` package, not an internal export of `agent.pw`.

Quickstart

This quickstart demonstrates how to initialize `agent.pw` with a PostgreSQL database, an encryption key, and an in-memory OAuth flow store, then resolves headers for a resource.

import { createAgentPw } from "agent.pw";
import { createInMemoryFlowStore } from "agent.pw/oauth";
import { createDb } from "agent.pw/sql";
import { unwrap } from "okay-error";

async function initializeAgentPw() {
  const databaseUrl = process.env.DATABASE_URL ?? '';
  if (!databaseUrl) {
    throw new Error("DATABASE_URL environment variable is required.");
  }
  const encryptionKey = process.env.AGENTPW_ENCRYPTION_KEY ?? '';
  if (!encryptionKey) {
    throw new Error("AGENTPW_ENCRYPTION_KEY environment variable is required.");
  }

  const db = unwrap(createDb(databaseUrl));
  const agentPw = await unwrap(
    createAgentPw({
      db,
      encryptionKey,
      flowStore: createInMemoryFlowStore(),
    }),
  );

  console.log('agent.pw initialized successfully.');
  
  // Example: Resolve headers for a previously connected resource
  const path = "acme.connections.docs"; // Replace with your resource path
  try {
    const headers = await unwrap(agentPw.connect.resolveHeaders({ path }));
    console.log(`Resolved headers for ${path}:`, headers);
  } catch (error) {
    console.error(`Failed to resolve headers for ${path}:`, error);
  }
  
  return agentPw;
}

initializeAgentPw().catch(console.error);