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 the recommended authentication method for interactive remote MCP clients. Pensyve publishes protected-resource and authorization-server discovery metadata, supports dynamic client registration, and requires PKCE S256. A compatible client can register the URL, open browser consent, and refresh its token without storing a Pensyve API key in project configuration.

How it works:

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

When to use OAuth: Interactive development with a compatible remote MCP client. OAuth tokens are short-lived and refreshed by the client.

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 Support

“Browser OAuth” means the client supports the remote MCP OAuth discovery flow. “Static bearer” is the API-key fallback; the exact secret-storage mechanism varies by client. Local stdio starts pensyve-mcp on the user's machine and does not use cloud authentication.

MCP Client Configuration

Claude Code (OAuth — Recommended)

Register the URL and let Claude Code discover OAuth:

claude mcp add --transport http pensyve https://mcp.pensyve.com/mcp

No API key is needed for the interactive flow.

Antigravity CLI

Install the native plugin:

agy plugin install https://github.com/major7apps/pensyve/tree/main/integrations/antigravity-plugin

Or register only the server:

agy mcp add pensyve https://mcp.pensyve.com/mcp

Open /mcp and choose Authenticate. See the Antigravity CLI guide for details.

Codex CLI

codex mcp add pensyve --url https://mcp.pensyve.com/mcp
codex mcp login pensyve

GitHub Copilot CLI

copilot mcp add --transport http pensyve https://mcp.pensyve.com/mcp

Copilot starts browser OAuth when the server first needs authentication. From an interactive Copilot CLI session, run /mcp auth pensyve to authenticate again or switch accounts.

OpenClaw

openclaw mcp add pensyve --url https://mcp.pensyve.com/mcp --transport streamable-http --auth oauth

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"

Use this bearer pattern only for non-interactive automation. The Pensyve Antigravity plugin and interactive URL-only registrations use OAuth instead.

Other MCP Clients

See the Remote MCP guide for URL-only configuration examples for Cursor, Cline, Windsurf, VS Code, OpenCode, Claude Desktop, and the qualified Continue paths.

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.