WavefrontDevelopers

Start

Authentication

The REST API takes workspace API keys. The MCP server takes OAuth tokens that act as the person who connected, and also accepts API keys for hosts that can only send a fixed header.

API keys

Owners create keys in the web app under Settings → API and MCP. A key belongs to one workspace, acts for the workspace rather than a person, and is shown once. Send it as a bearer token:

Authorization: Bearer wf_live_<prefix>_<secret>

Wavefront stores only a hash of the secret. Revoke a key in the same settings tab; keys made by an owner who is later demoted or removed are revoked with them.

Scopes

Pick at least one scope when you create a key. Each operation in the API reference names the scope it needs (x-required-scope in the OpenAPI document). A missing scope is 403 forbidden with details.missing.

ScopeAllows
context:readRead the workspace documents
context:writeUpdate the documents of an app-managed workspace
context:git-syncLegacy: reads the documents like context:read (use context:read instead)
generations:readRead the workspace: generations, versions, strategies, the calendar, schedules, publications, search data and suggestions
generations:writeCreate and revise drafts, answer questions, comment, plan with the strategist, manage the backlog and decide on suggestions
publishPublish and schedule approved versions to a destination
webhooksEvent webhooks for Zapier, Make or CI (subscribing also needs generations:read)
autopilotSet autopilot's cadence and backlog settings (auto-approve stays with an owner in the web app)
destinationsAdd, edit and test publishing destinations, including their credentials (owners are emailed); OAuth connects stay in the web app
integrationsRead, change and test Slack and Microsoft Teams settings (not connect them)
approveApprove versions or ask for changes. An approved version can be published, and when autopilot publishes on calendar dates it is scheduled automatically. Opt-in; versions with blockers still can't be approved

Workspace roles still apply to people: viewers read, editors also write and publish, and owners also manage the workspace.

Web-app-only actions

These need a person signed in to the web app. API keys never get them, and neither do MCP tokens. In the OpenAPI document they are marked x-session-only: true, and the API reference lists them separately.

  • Withdraw a publication, or mark one withdrawn by hand (owners).
  • Turn autopilot's auto-approve or auto-revise on or off (owners).
  • Change suggestion settings (owners). Approving, editing or dismissing a suggestion is allowed over MCP and for an API key with generations:write.
  • Make, see or revoke your calendar feed URL.
  • Create or leave a workspace, change your name, sign out other browsers, accept or decline an invitation, list and disconnect the agents connected as you.
  • Owner administration: members and invitations, API keys, destination credentials, limits, renaming, connecting and disconnecting Slack and Teams. Owners change Slack's and Teams' messages over MCP too.
  • Connect Google, Bing, Slack, Asana, Trello, Google Drive, Notion or Confluence.
  • Billing: choose a plan, buy credits, open the billing portal.
  • Post or schedule to a social network (Ayrshare, LinkedIn, X), or email a newsletter while publishing.

OAuth for MCP

The MCP server at https://wavefront.adwave.com/mcp uses the Streamable HTTP transport and OAuth 2.1. Most clients need only the URL: they discover the rest, register themselves and open the Wavefront sign-in and consent page in a browser.

  • Discovery. An unauthenticated call to /mcp returns 401 with a WWW-Authenticate header pointing at the protected resource metadata, https://wavefront.adwave.com/.well-known/oauth-protected-resource/mcp. The authorization server metadata is at https://wavefront.adwave.com/.well-known/oauth-authorization-server. Clients that treat the MCP URL as the issuer find the same documents at /.well-known/oauth-authorization-server/mcp and /mcp/.well-known/oauth-authorization-server. Wavefront is not an OpenID provider.
  • Client registration. Clients register with Dynamic Client Registration at /oauth/register, or use an https URL as their client_id (Client ID Metadata Documents). Redirect URIs must be https, http on a loopback host, or a private-use scheme for a desktop app (such as Cursor's).
  • PKCE is required. Tokens come from /oauth/token; sign-in and consent happen at /authorize.
ScopeAllows
mcp:readList workspaces; read documents, generations, versions and their files, version diffs and exports, strategies, the calendar, the backlog, comments, people, activity, destinations, publications, schedules, search performance, site metrics, suggestions and the balance; read the workspace, billing, credit estimates, integration status, suggestion settings, writing rules and imports. Owners also read event subscriptions, their deliveries and sample events.
mcp:writeGenerate, answer questions, revise, cancel and publish; schedule, reschedule and cancel publishing; talk to the strategist and edit, save and draft plans; manage the backlog; create, update and reset strategies; write, delete and restore documents; comment, delete comments and assign reviewers; apply an approved strategy version and set the writing rules; refresh the catalog and site metrics, sync search data, the project tool and imports, and detect suggestions; approve, edit and dismiss suggestions; change and stop imports. Owners also set autopilot, manage event subscriptions, add webhook destinations, edit and test destinations, and change and test Slack's and Microsoft Teams' messages.
mcp:approveApprove versions or ask for changes (wavefront_approve_version), for owners and editors. Offered unchecked as "Approve content" on the consent page, so a connection approves only when the person allowed it. An approved version can be published, and autopilot schedules approved calendar posts when publish on date is on.
offline_accessRefresh tokens, so the connection lasts.
  • Consent. The protected resource metadata lists mcp:read mcp:write, and the consent page offers every scope whatever the client asked for: read (required), write and stay connected, checked by default, and approve content, unchecked. The access token always carries the full scope of the grant; a scope the client sends on the code exchange or a refresh never narrows it. A grant without offline_access gets no refresh token.
  • Step-up. Calling a write tool with a token that still lacks mcp:write returns HTTP 403 with insufficient_scope. Clients that don't re-authorize on it leave the person to disconnect the app under Account → Connected agents and connect again with write checked; wavefront_whoami tells the agent so.
  • Lifetimes. Access tokens last 1 hour. Refresh tokens rotate on every use; the previous one keeps working until the client uses the new one. The grant lasts 30 days from when the person authorized it, however often it is refreshed, so connectors ask you to sign in again about once a month.
  • Roles still apply. A token acts as the person who connected, in the workspaces they belong to. A viewer's token can't write even with mcp:write, and only owners and editors can approve.
  • API keys on MCP. MCP OAuth tokens work only on /mcp; /v1 refuses them with 401. API keys work on both: on /mcp, generations:read counts as mcp:read and generations:write or publish as mcp:write, and each tool still checks the key scope its operation needs. A key can't step up: a write tool answers 403 insufficient_scope naming the key scopes to add, and an owner edits the key.

Hosts

Use https://wavefront.adwave.com: https://wavefront.adwave.com/v1 for the API and https://wavefront.adwave.com/mcp for MCP. Wavefront used to live at wavefront.adwave-apps.com. API clients, MCP connections and calendar feeds set up there keep working; pages opened there redirect to the new host. Set up new integrations on the new host.