Authentication

All API endpoints require a valid API key.

API Key Format

API keys follow the format bp_ followed by a random string:

bp_a1b2c3d4e5f6g7h8i9j0...

Keys are stored as SHA-256 hashes in the database. The plaintext key is only visible at creation time.

Sending Your Key

Include the API key as a Bearer token in the Authorization header:

curl https://api.based.page/deploy \
  -H "Authorization: Bearer bp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>"}'

Obtaining an API Key

Browser Login (MCP Server)

The MCP server's login tool opens your browser for email verification and generates a key saved to ~/.based-page/credentials.json.

Dashboard

Generate and manage keys at based.page/dashboard. From the dashboard you can:

• View active keys and their creation dates
• Generate new keys
• Revoke compromised keys

Agent Auto-Provisioning

For headless environments where browser login isn't possible, the API supports auto-provisioning agent identities:

curl -X POST https://api.based.page/auth/agent

Returns:

{
  "api_key": "bp_xxxxx",
  "agent_id": "abc123",
  "claim_token": "bpc_xxxxx",
  "claim_url": "https://based.page/claim?token=bpc_xxxxx"
}

Agent identities get free plan limits (5 deploys). The claim token allows a real user to later absorb the agent's deployments into their account.

Claiming Agent Deploys

Transfer an agent's deployments to your account:

curl -X POST https://api.based.page/auth/claim \
  -H "Authorization: Bearer bp_your_real_api_key" \
  -H "Content-Type: application/json" \
  -d '{"claim_token": "bpc_xxxxx"}'

Returns:

{
  "claimed": true,
  "agent_id": "abc123",
  "transferred_deployments": ["my-app", "other-site"]
}

After claiming:

• All deployments transfer to the claiming user
• The agent's API keys are invalidated
• The claim token is consumed (one-time use)
• The agent can auto-provision a new identity on its next deploy

Environment Variable

For CI/CD pipelines or headless environments:

export BASED_PAGE_API_KEY=bp_your_api_key_here

Or pass it through MCP server configuration:

{
  "mcpServers": {
    "based-page": {
      "command": "npx",
      "args": ["-y", "based-page"],
      "env": {
        "BASED_PAGE_API_KEY": "bp_your_api_key_here"
      }
    }
  }
}

If no API key is set and the user hasn't logged in, the MCP server auto-provisions an agent identity on first deploy. No configuration needed.

WARNING

API keys grant full access to your account. Do not commit them to version control, expose them in client-side code, or share them publicly.