Agent auth: OAuth + PKCE

OAuth connector access requires a provisioned PromptEden client record. Dynamic client registration is not exposed.

Before you start, get these from PromptEden:

• client_id
• Allowed redirect URI list
• Allowed scope list

Your connector must generate a PKCE code_verifier and S256 code_challenge for each authorization attempt.

PromptEden publishes OAuth metadata here:

GET https://app.prompteden.com/.well-known/oauth-authorization-server

The metadata advertises:

• authorization_endpoint: https://app.prompteden.com/oauth/authorize
• token_endpoint: https://app.prompteden.com/oauth/token
• response_types_supported: code
• grant_types_supported: authorization_code, refresh_token
• code_challenge_methods_supported: S256
• token_endpoint_auth_methods_supported: none

Send the user to PromptEden's authorization endpoint:

GET https://app.prompteden.com/oauth/authorize?response_type=code&client_id=YOUR_PROVISIONED_CLIENT_ID&redirect_uri=YOUR_REGISTERED_REDIRECT_URI&code_challenge=BASE64URL_SHA256_VERIFIER&code_challenge_method=S256&state=OPAQUE_STATE&scope=account:read%20projects:read%20monitors:read

PromptEden requires:

• response_type=code
• A provisioned, enabled client_id
• A registered redirect_uri
• code_challenge_method=S256
• A valid code_challenge
• state
• Scopes allowed for the seeded client

Exchange the code for tokens at /oauth/token. PromptEden treats these as public PKCE clients: do not send HTTP Basic auth and do not send client_secret.

curl -X POST https://app.prompteden.com/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=YOUR_PROVISIONED_CLIENT_ID' \
  --data-urlencode 'code=RETURNED_CODE' \
  --data-urlencode 'redirect_uri=YOUR_REGISTERED_REDIRECT_URI' \
  --data-urlencode 'code_verifier=ORIGINAL_CODE_VERIFIER'

The access token uses PromptEden's OAuth token prefix and can be sent as:

Authorization: Bearer poa_...

Refresh tokens are supported with grant_type=refresh_token.

Send the OAuth access token as a bearer token on REST routes:

curl https://app.prompteden.com/api/v1/monitors \
  -H "Authorization: Bearer poa_..."

OAuth tokens may call raw REST routes only for read-scoped operations. For approval-gated writes, use hosted MCP with a provisioned OAuth client. Use an API key for direct REST writes. The local stdio MCP server (npx -y @prompteden/mcp-server) also reads an API key from PROMPTEDEN_API_KEY, not an OAuth token.

Hosted MCP is also available over Streamable HTTP at https://app.prompteden.com/api/mcp. Send the API key as Authorization: Bearer pe_.... See MCP connection docs for setup and hosted write limits. Hosted MCP also accepts OAuth tokens for provisioned clients.

The MCP server 0.4.1 supports 29 tools: 20 public tools and 9 content-agent tools that appear only when content agents are enabled for the team. Content reads and writes run through hosted MCP, including from local stdio. Every content write returns an approval_required proposal with a browser link for an owner/admin decision. Content reads require content:read; writes require content:write. Hosted create_monitor and analytics_add_property_host also return approval proposals with a deepLinkUrl; other writes in the MCP guide are disabled on hosted MCP.

unauthorized_client. The client_id is missing, disabled, unknown, or not provisioned by PromptEden.

invalid_request: redirect_uri is not allowed. The redirect URI does not exactly match the seeded client record.

invalid_request: PKCE code_challenge_method must be S256. Plain PKCE is not supported.

invalid_scope. The requested scope is not in the client's allowed scope list.

invalid_token. The access token is invalid or expired.

403 plan_limit. The authorized workspace does not have API access.

403 insufficient_scope. The OAuth token is valid but missing a scope required by the REST route.

403 oauth_write_not_allowed. Raw REST writes with OAuth tokens are blocked. For provisioned OAuth clients, use hosted MCP to propose create_monitor or analytics_add_property_host, then have a workspace owner or admin review the action at the returned deepLinkUrl in PromptEden. For other local write tools, use an API key with the local stdio server. See MCP connection docs for permissions and limits.