CHouseUI
Access & security

Personal access tokens

Mint ch_pat_… tokens in Preferences to authenticate the CLI, MCP agents and CI — scoped, revocable, verified live — and manage the agents you connected by signing in.

In the app
Preferences › Personal access tokens/preferences

Personal access tokens (PATs) let the CLI, MCP agents, scripts and CI act as you without a browser. They look like ch_pat_… and are sent as Authorization: Bearer ch_pat_….

Create a token

  1. Preferences › Personal access tokens › New token.
  2. Give it a name that says where it's used (nightly-report, cursor-agent).
  3. Pick an expiry — 7, 30, 60 or 90 days, a custom date, or no expiry.
  4. Optionally narrow its scopes to a subset of your permissions. Scopes can only narrow what you can already do, never widen it.
  5. Copy the token. It is shown once; CHouse UI stores only a hash.

How a token is checked

  • A token carries your identity, not a frozen copy of your rights: every call checks your current roles, intersected with the token's scopes. Removing a role, deactivating you or revoking the token takes effect on the next call.
  • A scoped token is refused, with 403, on anything outside its scopes. That includes administration: a token scoped to table:select cannot list users or roles, even when you can.
  • An administrator's scoped token is checked for the kind of statement it runs, like anyone's: scoped to table:select it cannot run DDL. Data access policies still do not restrict an administrator's token.
  • A scoped token does not act as an administrator. If you are an admin or a super admin, your scoped token gets none of what the role alone allows: seeing other people's dashboards or scheduled queries, approving high-risk actions, assigning the super admin role, or changing a connection's kind, role map or links. Use a browser session, or a token without scopes, for those. It still reaches the same connections you do.
  • Data access policies apply exactly as in the UI.
  • Tokens are independent of browser sessions; signing out doesn't affect them.
  • Every MCP tool call is audited with the token's user, and agent activity appears on AI Governance.

Rotate and revoke

From the token's menu: Rotate token issues a new secret for the same token (update wherever it is used), Revoke token stops it immediately. Both are recorded in the audit log (pat.rotate, pat.revoke).

Tip: Create one token per consumer — each CI pipeline, each agent — with the smallest scopes and a sensible expiry, so you can revoke one without breaking the others.

Connected apps

Agents you connected by signing in are listed above your tokens. Each works on MCP only, with your live permissions, until it expires or you revoke it. The wrench sets its write tools, the bin revokes it at once (oauth.grant_revoke). Signing the same agent in again replaces its earlier access.

Connected apps in PreferencesTwo agents signed in with OAuth, each with its write tools, expiry and last use, above a personal access token

Where tokens are used

ConsumerHow
CLIchouse auth login prompts for it (or --token-stdin in CI)
MCP agentsRead from the CH_HOUSE_PAT environment variable or a secret prompt in the client config — or skip the token and sign in
ScriptsThe same /api/* endpoints the UI uses, with the bearer header

Treat a token like a password: it can do whatever its scopes and your roles allow.

Edit this page on GitHub ↗