Authentication

Pensyve supports two authentication methods for accessing the cloud API and remote MCP server:

Both methods access the same data. Choose based on your workflow.

API Keys

Creating a Key

1. Sign in at pensyve.com
2. Go to Dashboard → API Keys
3. Click Create Key
4. Choose a scope (see below)
5. Copy the key — it's only shown once

Key Scopes

Every API key has a scope that controls which operations it can perform:

The default scope is mcp (full access). Use the narrowest scope that fits your use case.

Key Rotation

Rotate keys without downtime:

1. Go to Dashboard → API Keys
2. Click Rotate on the key you want to replace
3. A new key is created with the same scope
4. The old key enters a 24-hour grace period — it still works
5. Update your environment with the new key
6. After 24 hours, the old key is automatically revoked

This gives you a full day to update all systems using the key.

Using Your API Key

API keys authenticate via the standard Authorization: Bearer header. Set the key in your environment so SDKs and MCP clients can reference it:

export PENSYVE_API_KEY="psy_your_key_here"

Add to your shell profile (~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish) to persist across sessions.

When configuring MCP clients, pass the key as a Bearer token in the headers block — not in the env block. The headers approach explicitly sets the Authorization header on every HTTP request, which is the standard pattern for HTTP-transport MCP servers:

{
  "mcpServers": {
    "pensyve": {
      "type": "http",
      "url": "https://mcp.pensyve.com/mcp",
      "headers": {
        "Authorization": "Bearer ${PENSYVE_API_KEY}"
      }
    }
  }
}

OAuth 2.1 (PKCE)

OAuth is used by the Claude Code plugin and VS Code extension. It requires no manual setup — the plugin handles the browser-based consent flow automatically.

How it works:

1. Plugin initiates authorization via /.well-known/oauth-authorization-server
2. Browser opens the Pensyve consent page
3. You approve access
4. Plugin receives a JWT access token signed with Ed25519
5. The gateway verifies the token on every request

When to use OAuth: Interactive development where you're using Claude Code or VS Code directly. OAuth tokens are short-lived and automatically refreshed.

When to use API keys instead: CI/CD pipelines, automation scripts, non-interactive environments, or MCP clients that don't support OAuth discovery.

MCP Client Configuration

Claude Code (OAuth — Recommended)

Install the plugin for automatic OAuth authentication:

claude plugins add pensyve

No API key needed — the plugin handles authentication via browser consent.

Claude Code (API Key — CI/Automation)

For non-interactive environments or when you prefer explicit key management:

export PENSYVE_API_KEY="psy_your_key_here"
claude mcp add --transport http pensyve https://mcp.pensyve.com/mcp \
  --header "Authorization: Bearer $PENSYVE_API_KEY"

This is the same Bearer token pattern used by the Pensyve plugin internally.

Other MCP Clients

See the Remote MCP guide for per-client configuration (Cursor, Cline, Windsurf, VS Code, Claude Desktop, Continue). All clients use the same pattern: set PENSYVE_API_KEY in your environment, then pass it as Authorization: Bearer in the headers block of your MCP config.

SDK Authentication

Python

import pensyve

p = pensyve.Pensyve(
    api_url="https://api.pensyve.com",
    api_key="psy_your_key_here",
    namespace="my-agent",
)

Or use the environment variable:

import os
p = pensyve.Pensyve(
    api_url="https://api.pensyve.com",
    api_key=os.environ["PENSYVE_API_KEY"],
    namespace="my-agent",
)

TypeScript

import { Pensyve } from "pensyve";

const p = new Pensyve({
  baseUrl: "https://api.pensyve.com",
  apiKey: "psy_your_key_here",
});

Go

client := pensyve.New(
    pensyve.WithAPIKey("psy_your_key_here"),
    pensyve.WithBaseURL("https://api.pensyve.com"),
)

REST API

curl https://api.pensyve.com/v1/recall \
  -H "Authorization: Bearer psy_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "user preferences", "namespace": "my-agent"}'

Security Best Practices

• Never commit API keys to version control. Use environment variables or secret managers.
• Use the narrowest scope — mcp:read for agents that only recall, mcp:write for ingestion pipelines.
• Rotate keys regularly — the 24-hour grace period makes this zero-downtime.
• Revoke compromised keys immediately from the dashboard.
• One key per environment — separate keys for dev, staging, and production.
• The gateway never logs plaintext keys — only the first 8 characters appear in debug logs.