Authentication

Credentials

curl https://api.trytree.house/api/workspace \
  -H "x-api-key: th_example_key"

Kinds of key

Every key also carries an actor type, agent or human. It is how Treehouse attributes changes: every write, move, delete and comment made with the key is recorded with that principal, together with the key's id and name. The activity feed shows agent changes as agent changes because the key says so, not because of which endpoint was used.

Keys from the web app

In the web app, open the account menu and choose API keys. Used by sets the actor type:

Keys created here are account-wide. The key is shown once, when you create it. The API keys page covers the UI in detail.

Keys from the device flow

The desktop app and treehouse login get a workspace-scoped key through the device authorisation flow below. These keys default to the human actor type.

Key management endpoints

These accept a browser session cookie only. A request carrying x-api-key is refused with 403 and the message Key management requires a logged-in session, not an API key, so a leaked key can never mint or revoke other keys.

actorType is agent or human; anything else is treated as human. name defaults to treehouse-key (account-wide) or treehouse-cli (workspace-scoped). With workspaceId, you must be a member of that workspace.

Device authorisation flow

A client with no browser session (the CLI, the desktop app, or your own tool) can get a workspace-scoped key by asking the user to approve it in the web app. It follows the shape of OAuth device authorisation (RFC 8628).

1. The client calls POST /api/device/code with no credentials.
2. The client shows the user verification_uri_complete (the web app's /link page, with the code filled in) and user_code.
3. The user signs in, picks a workspace and approves.
4. The client polls GET /api/device/poll?device_code=<device_code> every interval seconds until it gets the key.

POST /api/device/code returns:

{
  "device_code": "…",
  "user_code": "ABCD-EFGH",
  "verification_uri": "https://app.trytree.house/link",
  "verification_uri_complete": "https://app.trytree.house/link?code=ABCD-EFGH",
  "expires_in": 600,
  "interval": 5
}

The code expires after 10 minutes and can be used once.

Poll responses

api_base is the API's own public URL, so a client that started from the app URL learns where to send requests.

Errors and limits

A missing or invalid credential returns 401. When an API key is rejected, the error's data explains why:

{ "error": "invalid_api_key", "reason": "INVALID_API_KEY" }

reason is the auth library's code for the specific failure (for example a key that was deleted or has expired), so a client can tell a revoked key from a transient problem.

A valid key used on a workspace it can't reach returns 403 with Key is not scoped to this workspace (a workspace-scoped key) or Not a workspace member. An unknown workspace returns 404.

There is no per-key rate limit: the sync CLI and agents authenticate on every request. The device endpoints are limited: POST /api/device/code to 5 requests per 10 minutes per IP address, and approvals to 10 per 15 minutes per user. Over the limit returns 429.

When someone leaves a workspace

When a member is removed from a workspace, or leaves it:

• Their workspace-scoped keys for that workspace are deleted. A synced folder using one stops syncing and asks them to sign in again.
• Their account-wide keys keep working for their other workspaces, but get 403 Not a workspace member for this one.

Keeping keys safe

• One key per agent or integration. The key's name appears in the activity feed, so separate keys make it clear who did what, and you can revoke one without breaking the others.
• Revoke keys you no longer use, from API keys in the web app or with DELETE /api/keys/{id}.
• Never commit a key to a repository or paste it into a shared file. Treat it like a password: anyone holding it can read and write every workspace it reaches.
• The CLI stores its key in <folder>/.treehouse/config.json with file mode 0600 (readable only by you). Keep .treehouse/ out of version control.