Documentation

Authentication

CLI and MCP both authenticate with an API key — the same credential type, minted in the same place. .ctx is different: inside an Ambassador you're already authenticated as a server-side context scoped to that app, no API key involved (see .ctx overview).

If you're looking for Site Auth — how a Host app authenticates its own end users — see Site Auth instead. That's a different system: Site Auth signs people into apps you build; API keys authenticate your own CLI/MCP session against Waymaker.

Minting an API key

Sign in at admin.waymakerone.com
Go to /api/keys
Click Create API Key
Name it and tick permissions
Copy the key immediately — it's shown once, starts with wm_sk_, and can't be viewed again

Every member mints their own keys — a key acts as the person who created it, so never use one someone else minted for you. Who can do what:

Any member can mint, list and revoke their own keys.
Only an organization owner/admin can mint a key carrying host:admin. A member who asks for it is refused (403); a member who sends no permissions gets the default without it.
Organization owners/admins can list and revoke every key in the organization.
A key stops working when its creator leaves the organization — validation requires the creator to still be an active member of the key's org.

See Managing API keys for rotating and revoking.

Permissions

A key carries one or more of these seven, ticked individually when you create it (everything except host:admin is ticked by default). Any other value is refused (400), and host:admin requires an organization owner/admin:

Permission	Grants
`commander:read`	Read Commander data — tasks, documents, goals, sheets, and more
`commander:write`	Create, update, delete Commander data
`host:read`	Read Host apps, Ambassadors, and their status
`host:deploy`	Deploy and manage Host apps/Ambassadors
`host:admin`	Host admin operations — leave unticked unless you specifically need it
`sync:read`	Read access for `waymaker sync` (deprecated — removed in the next CLI release)
`sync:write`	Write access for `waymaker sync` (deprecated — removed in the next CLI release)

How MCP sees these

MCP collapses your key's permissions into two effective scopes: any :read permission grants MCP read, and :write/:deploy/:admin all grant MCP write (which implies read too) — a read-only key won't see write-shaped tools at all. sync:read/sync:write do not currently grant the MCP sync scope — a server-side naming mismatch, not something this key or its permissions can work around. See the cached-tool-list gotcha for what else this affects.

Using the key

CLI

export WAYMAKER_API_KEY=wm_sk_your_key_here

Or add it to a .env file in your project — the CLI loads it automatically. Verify with:

waymaker auth status

MCP

Pass it as a bearer token when configuring the server in your AI client:

{
  "mcpServers": {
    "waymaker": {
      "type": "http",
      "url": "https://mcp.waymakerone.com/mcp",
      "headers": { "Authorization": "Bearer wm_sk_your_key_here" }
    }
  }
}

Rotating or revoking a key

Revoke a compromised or unused key from admin.waymakerone.com/api/keys — it stops working immediately for both CLI and MCP. There's no separate revoke step per front-end.