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

Hosted MCP protected-resource metadata is available at:

GET https://app.prompteden.com/.well-known/oauth-protected-resource

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&resource=https%3A%2F%2Fapp.prompteden.com%2Fapi%2Fmcp

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

When resource is present, it must equal https://app.prompteden.com/api/mcp.

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.

OAuth bearer tokens work with hosted MCP:

{
  "mcpServers": {
    "prompteden": {
      "url": "https://app.prompteden.com/api/mcp",
      "headers": {
        "Authorization": "Bearer poa_..."
      }
    }
  }
}

OAuth tokens may call raw REST routes only for read-scoped operations. For writes, use hosted MCP. The current protocol returns approval_required and routes the action through the app workflow.

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 MCP tool or REST route.

403 oauth_write_not_allowed. The token was used on a raw REST write route. Use hosted MCP for workflow-gated writes.