Documentation

The app's context key

An app's server calls its context API (host-context-api) to read and write its Host Tables, read its team, and use whatever else an org admin has granted the app. A context key is the app's own credential for that, so your server never holds a person's API key.

A context key:

reaches this app's context API only, within the app's own grants, and nothing else;
is issued by Waymaker and placed straight into the app's environment, so nobody has to hold it;
can be rotated or revoked at any time, and is never shown again after it is issued.

Where the key lives. Waymaker's record of the key is only a hash, used to recognise it. The key itself is in the app's environment variables, because the app's server needs it to call. So anyone who can read the app's environment (its build and runtime, and the people who can manage the app) can read the key. Every Waymaker screen, CLI command and MCP tool that lists env variables masks it. What keeps it safe is how little it can do (this app's context API, within the app's grants) and that it can be revoked at once.

Issue it

waymaker host apps context-key create <app-id>   # into the app's env as WAYMAKER_CONTEXT_KEY; never shown
waymaker host apps deploy <app-id>               # the variable reaches the app on its next deploy

Then, from server-side code:

await fetch('https://apps.waymakerone.com/functions/v1/host-context-api', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.WAYMAKER_CONTEXT_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ action: 'commander_team', data: {} }),
})

The key names its app, so X-App-Id is not needed. If you send X-App-Id, it must be this app's id.

With the context SDK, pass contextKey:

const client = new WaymakerClient({ contextKey: process.env.WAYMAKER_CONTEXT_KEY, workspaceId })

Keep the key server-side. Never put it in a variable your framework compiles into the browser bundle.

Listing an app's keys needs the same role as managing them (below).

Commands

Command	What it does
`context-key create <app-id> [--env-name NAME \| --show]`	One key per app. Into the env by default; `--show` prints it once instead.
`context-key rotate <app-id> [--env-name NAME \| --show]`	New key; the old one stops working immediately. Redeploy the app straight after.
`context-key revoke <app-id> --confirm`	Stops it, and removes it from the env if it was placed there.
`context-key list <app-id>`	Prefix, env variable, created, last used, revoked. Never the key.

All of them sit under waymaker host apps. The MCP tools are host_app_context_key_create, host_app_context_key_rotate, host_app_context_key_revoke and host_app_context_key_list; through MCP the key always goes into the app's env and is never returned.

The env variable must be a server-side name:

names starting with _ are refused;
browser-bundle prefixes (VITE_, NEXT_PUBLIC_, …) are refused;
WAYMAKER_ names are refused, except WAYMAKER_CONTEXT_KEY itself.

Creating, rotating and revoking need the owner or releaser role on the app's Solution. Outside a Solution, the app's creator or an organisation admin can do it.

A key lasts only as long as its creator's access. When the person who created it leaves the organisation, or loses the owner or releaser role:

a key that was shown to them (--show) stops working at its next use;
a key that only ever went into the env is rotated at its next use instead. A new key goes into the same variable, and the old one keeps working for 72 hours so the app can redeploy.

The organisation's owners are emailed either way.

Errors

Status	When
`401`	The key is unknown, malformed, revoked or past its rotation window, its app no longer exists, or `X-App-Id` names a different app. These all look the same.
`403`	The app has not been granted what the action needs.

Moving off `WAYMAKER_API_KEY`

Before context keys, an app put a key in its env by hand as WAYMAKER_API_KEY and sent it as X-API-Key with X-App-Id. That still works for now, but every response to it carries Deprecation: true, and it will be removed. To move:

waymaker host apps context-key create <app-id>, then redeploy.
Switch the app's calls to Authorization: Bearer $WAYMAKER_CONTEXT_KEY, then redeploy.
Delete WAYMAKER_API_KEY from the app's env. If it held a person's API key (wm_sk_…), revoke that key under Admin → API keys too.

When the last app has moved, Waymaker can switch the old path off before it is removed. From then on, an X-API-Key that is not a context key is refused with 401.

The app's context key

Issue it

Commands

Errors

Moving off WAYMAKER_API_KEY

Moving off `WAYMAKER_API_KEY`