REST API & authentication

datahashi runs as two processes with two API surfaces. They are separated on purpose — see Architecture.

Control plane — hashi-api

Browser-reachable. Manages workspaces, membership, sources and connections, semantic models, and credentials. It holds the key that seals warehouse credentials and it never runs SQL.

Endpoint	Purpose
POST /v1/orgs/{orgId}/api-keys	mint a data-plane key (mode: governed | explore)
GET /v1/orgs/{orgId}/api-keys	list keys by metadata — never returns secrets
key revoke / rotate	invalidate or roll a credential without downtime
authoring + publish routes	apply a draft model, publish an artifact

Authentication: a console session, or a control-plane token, depending on the route.

Engine — hashi-engine

Holds the live warehouse connections and compiles SQL. Never exposed to a browser. This is where queries actually run.

Endpoint	Method	Function
/v1/query	POST	run a Semantic Query
/v1/models	GET	list semantic model names
/v1/catalog	GET	metrics, dimensions, views (measures in explore mode)
/v1/describe	GET	look up one metric, dimension, or measure
/v1/tenants/{id}/usage/summary	GET	metered usage over a window
/mcp	—	the MCP protocol surface

Authentication: Authorization: Bearer <data-plane key>. The key’s claims are identity only — your workspace and mode. The warehouse a query reaches, its row-level security, and its cost limits are resolved server-side.

Credentials

Credential	Carried where	Used for
Console session	cookie	a member driving the console and playground
Query-time JWT	Authorization, exp ≤ 120s	the control plane proxying a member’s playground query to the engine — identity travels here, never in the body
Data-plane API key	Authorization: Bearer	a REST or MCP consumer; scoped to a principal and a mode

Error envelope

Data-plane errors are JSON:

{ "error": { "code": "not_found", "message": "unknown metric: revenu" } }

Stable codes: bad_request, unauthenticated, forbidden, not_found, over_budget, overloaded, internal. Router-level errors (wrong method or path) return a plain-text 404/405 outside this envelope.