Skip to main content
IP BotPLATFORM
Docs navigation

Authentication

API keys, the two auth modes, and the user-id rule for agents.

Every IP Bot surface — app, CLI, MCP server — authenticates the same way. The GraphQL endpoint is shared across all users; only your key is yours.

Prerequisite: a key (private beta)

IP Bot is in private beta. You need an ipbot_live_… key before any npx / MCP / skill step will work — request access, then copy your key from Settings → API Keys. Without a valid key, calls fail with UNAUTHENTICATED.

Two auth modes

  • Human (interactive) — ipbot auth login runs a Cognito Authorization-Code + PKCE flow in your browser and caches a token. Best at a real keyboard.
  • Agent (API key) — set IPBOT_API_KEY=ipbot_live_… and the key identifies you on every call. Best for CI, scripts, and MCP clients.

Check who you are and how you're authed at any time:

bash
> npx @island-pitch/ip-bot-cli auth whoami --output json

Environment variables

VariableWhat it's for
IPBOT_APPSYNC_ENDPOINTThe platform GraphQL endpoint. Same for everyone.
IPBOT_API_KEYYour per-user key (ipbot_live_…). Authenticates you and debits your Winds.
IPBOT_USER_IDYour Cognito sub. Default user for commands that act on a user (content, calendar, org). Get it from `ipbot auth whoami`.
IPBOT_AUTH_TOKENOptional Cognito ID token instead of an API key (interactive/human auth).
bash
> export IPBOT_APPSYNC_ENDPOINT=https://api.islandpitch.bot/graphql
> export IPBOT_API_KEY=ipbot_live_xxxxxxxxxxxxxxxx

The user-id rule (important for agents)

Powers and Winds are resolved from your key — they need no user id. Content, calendar, and org commands act on behalf of a user, so under API-key auth they need your Cognito sub. Provide it with --user-id <sub> (CLI) / the userId arg (MCP), or set IPBOT_USER_ID once. If neither is set, those commands error clearly rather than returning empty data.

bash
> # one-time: make your sub the default for user-scoped commands
> export IPBOT_USER_ID=$(npx @island-pitch/ip-bot-cli auth whoami --output json | jq -r .userId)
> npx @island-pitch/ip-bot-cli content list --output json

Key rotation & scopes

  • Create, name, and revoke keys in Settings → API Keys. Revoking is immediate.
  • A key inherits your license + Winds; it cannot exceed your own permissions.
  • Rotate by issuing a new key, updating IPBOT_API_KEY, then revoking the old one.
  • Treat keys like passwords — never commit them or paste them into shared logs.

Hitting auth errors? See Troubleshooting.