Authentication

Every Podwise surface uses one of four credentials. Picking the wrong one is the most common reason a first request fails, so start with what you are connecting.

Sign in to the web appCopy Anchor Link

Sign in at app.podwise.ai with Google, Apple, GitHub, email and password, or a magic link. Use one method per person: a different method with a different address creates a separate account, with its own subscription and Library.

The session is what approves the OAuth requests below. You do not copy anything out of the browser for the plugin or the hosted MCP server.

OAuth for AI appsCopy Anchor Link

The hosted MCP server at https://mcp.podwise.ai/mcp authorizes apps with OAuth. When an app connects for the first time, it opens a Podwise page in your browser; sign in if needed and click Allow. The app receives its own grant, not your password and not an API token.

• Where to approve it: inside the app's own flow. The per-client steps for Claude, ChatGPT, Claude Code, Cursor, VS Code, and Codex are in MCP Server.
• Where to review it: Settings › Connections › Connected apps lists every app you authorized, when it connected, and when it was last active.
• How to revoke it: click Disconnect on that page. Access stops immediately; the app can reconnect later with a new approval.

The server supports OAuth Client ID Metadata Documents and Dynamic Client Registration, so a client does not need a client ID or secret from you.

If an app cannot run an OAuth browser flow — a headless agent, a CI job, a container — use an API access token instead.

API access tokensCopy Anchor Link

An API access token is a long-lived Bearer token you create and revoke yourself. It works with:

• the Open API (/api/open/v1),
• the Enterprise API (/api/ent/v1) for accounts with an Enterprise entitlement,
• the MCP server, for clients that send a header instead of doing OAuth.

Create one on Settings › Developer. Enterprise customers can also create tokens in the Enterprise Console.

Send it in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

One token works with both API families. Use the same token for /api/open/v1 and /api/ent/v1; each family applies its own access rules and rate limits.

Enterprise API requests are limited to 10,000 requests per user per hour. A rate-limited request returns HTTP 429; wait for the number of seconds in the Retry-After header, then retry.

Tokens with MCP clientsCopy Anchor Link

An MCP client that supports headers can skip the browser flow:

claude mcp add --transport http podwise https://mcp.podwise.ai/mcp \
  --header "Authorization: Bearer YOUR_API_TOKEN"

{
  "mcpServers": {
    "podwise": {
      "url": "https://mcp.podwise.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
    }
  }
}

Codex can read the token from an environment variable instead of storing it in a config file:

export PODWISE_API_TOKEN=YOUR_API_TOKEN
codex mcp add podwise --url https://mcp.podwise.ai/mcp --bearer-token-env-var PODWISE_API_TOKEN

Apps connected with a token do not appear in Settings › Connections. They are managed as tokens, on the Developer page.

CLI loginCopy Anchor Link

The CLI stores its own API access token rather than asking for one on every command:

podwise auth            # opens the browser and saves the key
podwise config show     # prints the current configuration

If you already have a token, set it directly:

podwise config set api_key your-sk-xxxx

The configuration is written to ~/.config/podwise/config.toml. Nothing is shared with the web app; revoking a token on the Developer page also logs the CLI out.

Keeping credentials safeCopy Anchor Link

• Treat an API access token like a password. Anyone with it can act on your account until you delete it.
• Keep tokens out of git, logs, and screenshots. Prefer an environment variable where the tool supports one.
• Revoke tokens you no longer use on the Developer page, and disconnect apps that should lose access.
• If a token leaks, delete it first, then create a replacement. Deleting is immediate; the CLI or script fails with 401 on its next call.

TroubleshootingCopy Anchor Link