# PromptEden

PromptEden provides AI visibility monitoring, competitor comparisons, and Eden analysis. Content creation and publishing are private features retained for a fixed group of existing subscriber teams. New subscriptions do not unlock them.

## BYOA Connection Model

Agents can use REST with pe_ API keys, hosted MCP at https://app.prompteden.com/api/mcp, or OAuth authorization-code with PKCE S256.

Existing-account delegated auth:
- Do not ask the human for their PromptEden password.
- Preferred API-key handoff: ask an owner/admin to open Workspace Settings > API Keys, create a scoped key for this agent, and paste the one-time pe_ key back.
- OAuth handoff: fetch /.well-known/oauth-authorization-server, construct an authorization-code + PKCE S256 URL for your registered public client, and ask the human to approve the scopes.
- The old /api/v1/agent/sign-in password path is compatibility-only and should not be used as a BYOA handoff for an existing human account.

## OAuth Discovery

GET https://app.prompteden.com/.well-known/oauth-protected-resource/api/mcp returns public resource metadata for hosted MCP.
GET https://app.prompteden.com/.well-known/oauth-authorization-server returns public authorization-server metadata.
POST https://app.prompteden.com/oauth/token accepts application/x-www-form-urlencoded OAuth grants and returns JSON errors such as invalid_request, invalid_client, invalid_grant, unsupported_grant_type, or invalid_token. It never returns sign-in HTML.

## Human Handoff

For an API-key handoff, send the human this message:
"Open PromptEden, go to Workspace Settings > API Keys, create a scoped key named for this agent, and paste the pe_ key back here. Do not send your password."

For OAuth, send the human the authorize URL generated from discovery metadata. They sign in, review scopes, approve or cancel, and the agent receives the localhost callback or redirect result.

Phase-1 OAuth supports only 13 public reads: get_account, list_monitors, get_results, list_providers, list_projects, get_project, preview_displacement_scan, agent_status, analytics_get_property, analytics_get_verification, analytics_get_traffic, analytics_get_overview, analytics_list_goals. REST rejects poa_ tokens with 401 invalid_token. Writes, private tools, agent_sign_up, agent_sign_in, and check_approval are unavailable through OAuth. OAuth uses exact scopes and the consent project ceiling; an empty ceiling allows no projects. API-key hosted writes can use the approval bridge and check_approval.

## API-Key Approval Contract

API-key hosted MCP write proposals return approval_required with approvalId, approvalUrl, expiresAt, pollAfterSeconds, statusUrl/tool instructions, requested scopes, and a frozen action summary. Poll check_approval every 5 seconds or slower. Stop on rejected or expired. Continue on approved until executionResult appears, or failed returns a recovery message.

## Scopes Per Endpoint

Scopes are <resource>:<read|write> over public feature areas (account, teams, projects, monitors, prompts, results, providers, domains, gsc, citations, brand, billing, referrals, displacement, eden, exports, audits, alerts, analytics). The single scope * grants full access, including future scopes. Broad legacy scopes imply their narrow split-outs (monitors:* implies providers:*, prompts:*, displacement:*).

account:read -> /api/v1/account, /api/v1/agent/status, check_approval
projects:read -> GET /api/v1/projects, GET /api/v1/projects/{projectId}
projects:write -> POST /api/v1/projects (denied to project-restricted keys)
monitors:read -> GET /api/v1/monitors
monitors:write -> POST /api/v1/monitors
results:read -> GET /api/v1/monitors/{monitorId}/results
providers:read -> GET /api/v1/monitoring/providers
analytics:read -> GET /api/v1/analytics/property, GET /api/v1/analytics/property/verification, GET /api/v1/analytics/traffic, GET /api/v1/analytics/overview, GET /api/v1/analytics/goals
analytics:write -> PATCH /api/v1/analytics/property, POST /api/v1/analytics/property, POST /api/v1/analytics/property/key/rotate, POST /api/v1/analytics/property/verification, POST /api/v1/analytics/goals, DELETE /api/v1/analytics/goals/{goalId}

## Project-Restricted Keys

API keys may carry a project allowlist. Requests resolving to a project outside the allowlist fail with 403 project_forbidden. List endpoints (GET /api/v1/projects, GET /api/v1/monitors) filter to allowed projects instead of failing. Keys without a restriction reach all projects.

## Error Catalog

unauthorized: no bearer credential was sent. Add Authorization: Bearer.
invalid_token: the bearer credential is malformed, expired, revoked, or unknown. Refresh OAuth or ask for a new API key.
insufficient_scope: ask for the listed scope.
project_forbidden: the API key is restricted to specific projects and this request targets another project. Ask for a key covering the project.
approval_required: open approvalUrl and poll check_approval.
approval_rejected: stop unless the human asks for a revised proposal.
approval_expired: create a new proposal only after human intent is clear.
plan_limit: the workspace plan does not include the requested capability.
rate_limit_exceeded: wait for Retry-After.