WavefrontDevelopers

Start

Authentication

The REST API takes workspace API keys. The MCP server takes OAuth tokens that act as the person who connected. Each only works on its own surface.

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)

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.

  • Approve a version (owners and editors).
  • 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 refused over MCP, but allowed 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.
  • Owner administration: members and invitations, API keys, destinations, limits, renaming, Slack and Teams.
  • 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:readRead workspaces, documents, generations, versions, strategies, the calendar, the backlog, comments, destinations, publications, schedules, search data, suggestions and the balance.
mcp:writeGenerate, answer questions, revise, cancel, publish and schedule; plan with the strategist; manage the backlog, strategies and documents; comment and assign reviewers.
offline_accessRefresh tokens, so the connection lasts.
  • Step-up. Clients may ask for mcp:read first. Calling a write tool without mcp:write returns HTTP 403 with insufficient_scope, and the client asks the person to grant write access.
  • 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 no token can approve.
  • One surface each. MCP tokens work only on /mcp; /v1 refuses them with 401. API keys work only on /v1.

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.