Skip to main content
The ShoulderTap HTTP API is served by shtap serve at /api/v1 on your host (default http://localhost:8776/api/v1). It authenticates every request — except the Slack events endpoint — with a single static bearer token.

​
The token

There are no user accounts and no per-key scopes. The whole API is guarded by one shared secret. Its value comes from an environment variable named by server.api_token_env in shouldertap.yaml, which defaults to SHOULDERTAP_API_TOKEN.
.env
Set it before starting the server. The CLI, SDK, and MCP server all read the same token to call the engine.
If the token environment variable is unset, authentication is disabled — every request is accepted and the server logs a warning on startup. This is convenient for a first local run, but never expose the server beyond localhost without setting the token.

​
Send the token

Pass it as a bearer token in the Authorization header:
A missing or incorrect token returns 401 Unauthorized.

​
The Slack exception

POST /api/v1/slack/events does not use the bearer token — Slack signs its own requests, and ShoulderTap verifies them with the Slack signing secret instead. See Connect Slack. Every other route requires the bearer token.
Keep the token in an environment variable rather than hard-coding it. In Python, os.environ["SHOULDERTAP_API_TOKEN"]; in Node, process.env.SHOULDERTAP_API_TOKEN. Because it’s a single shared secret with full access, rotate it by changing the environment variable and restarting the server.