API Keys and Scopes

Choose the right SaaSFunnels key or hosted OAuth path for CLI diagnostics, MCP reads, and Direct API smoke events.

SaaSFunnels developer tools use scoped workspace API keys. Use the narrowest key that matches the task.

Scopes

Scope	Use it for	Environment variable
`developer:read`	CLI diagnostics, readiness checks, MCP live read tools, mapping gaps, recent signals, safe payload previews.	`SAASFUNNELS_API_KEY`
`direct:write`	Direct API event ingestion and setup smoke events.	`SAASFUNNELS_INGEST_API_KEY`
`events:write`	Generic event ingestion and setup smoke events.	`SAASFUNNELS_INGEST_API_KEY`

Local commands such as saasfunnels init, saasfunnels agent install, saasfunnels events sample, and saasfunnels events validate do not need credentials.

Create and revoke a developer key

Workspace admins can manage both credential types through the existing Direct API → Credentials surface:

Choose Create key.
Choose Developer tools for developer:read, or Event ingestion for direct:write.
Copy the value when it appears. It is shown only once.
Use the row action later to rotate or revoke the key.

Creating a developer key does not mark Direct API ingestion as configured. Non-admin members can use a key supplied through an approved secret manager but cannot create, rotate, or revoke workspace keys.

Interactive hosted MCP does not need either key. It uses Clerk sign-in, the selected Organization, current workspace membership, and server-side capability policy on every tool call.

Configure live diagnostics

Set the read key for CLI diagnostics and MCP sessions:

export SAASFUNNELS_API_KEY=<DEVELOPER_READ_KEY>

Use it with:

saasfunnels doctor
saasfunnels readiness --json
saasfunnels mcp serve

Do not put SAASFUNNELS_API_KEY in hosted MCP client configuration.

Configure smoke event writes

Set the ingest key only in server-safe environments:

export SAASFUNNELS_INGEST_API_KEY=<SAASFUNNELS_INGEST_KEY>

Use it with:

saasfunnels events send-test --json

Do not use an ingest key as the MCP read key. Do not use a developer read key for event ingestion.

Configure API base URL

Use SAASFUNNELS_API_BASE_URL only for non-production or staging-safe checks:

export SAASFUNNELS_API_BASE_URL=https://app.prevenue.ai

This current-host value is for the private test window. The final public default changes to https://app.saasfunnels.ai after the coordinated domain cutover.

Secret handling

Prefer environment variables over command arguments for secrets.
Do not paste full keys into prompts, screenshots, committed files, shell history examples, generated handoff files, or browser code.
Rotate keys that were shared with an agent, logged, or committed.
Keep SAASFUNNELS_INGEST_API_KEY out of MCP client configs unless send_test_event is explicitly enabled for setup smoke testing.
Live API reads and writes resolve the workspace server-side from the key. Hosted MCP resolves it from the selected Clerk Organization. Do not let request bodies choose the workspace.