Skip to main content

API authentication

The API uses bearer authentication.
/v1 accepts two kinds of credentials, both scoped to your workspace:
  • API keys (sk_…), for scripts and automation. Only organization owners and admins can generate a key from the app.
  • CLI login tokens, from tth auth login. Any member of the workspace can use them.
IMPORTANT: Generating a new API key revokes your previous key. Example:

CLI authentication

The CLI signs you in through your browser:
It shows a one-time code and opens TalkToHumans to confirm it, then saves the login in ~/.config/talktohumans/credentials.json, readable by you only. tth auth status shows the workspace and credential in use, and tth auth logout deletes the saved login. Cron jobs and scripts have no one to confirm in a browser. Give them an API key with the TTH_API_KEY environment variable, which wins over the saved login, or save one with tth auth login --with-token < api-key.txt. A login with no workspace yet returns 403 with the code workspace_setup_required. Open the web app with the same email to finish setup, then run the command again. If you belong to several workspaces, use an API key from the one you want.

MCP authentication

The MCP uses OAuth bearer authentication, not TalkToHumans API keys. MCP endpoint: