Authentication

Hoist has two authentication surfaces. REST API and CLI calls use a Hoist API key. MCP clients obtain a scoped access token through OAuth consent after a signed-in human approves access — there is no token to paste for MCP.

REST API and CLI keys

Provisioned accounts use a native Hoist API key. Keys are prefixed ha_live_ and are sent as a bearer credential on every request except GET /v1/_health.

Authorization header

Authorization: Bearer ha_live_xxxxxxxxxxxxxxxxxxxxxxxx

Credential handling.Treat an API key like a password. Do not place it in browser code, public repos, screenshots, prompts, or analytics payloads.

The CLI uses the same key. Pass it with --token or set the HOIST_API_KEY environment variable. The API key is the single credential for both REST and CLI — there is no separate CLI credential flow.

MCP OAuth consent

MCP clients use OAuth consent — the AI host handles the flow and no API key is pasted into the host. A human approves the scopes the AI client can use, and Hoist stores the approval and audit events server-side. Currently available workflows are free and unmetered: OAuth consent does not trigger per-call billing, normal customer checkout is unavailable, and billing setup cannot unlock an unavailable tool.

Use this issuer and route set:

Route	Purpose
https://mcp.assets.hoistai.com/.well-known/oauth-authorization-server	OAuth metadata
https://mcp.assets.hoistai.com/oauth/register	Dynamic client registration
https://mcp.assets.hoistai.com/oauth/authorize	Human approval
https://mcp.assets.hoistai.com/oauth/token	Token exchange
https://mcp.assets.hoistai.com/oauth/revoke	Disconnect or revoke
https://mcp.assets.hoistai.com/mcp	Protected MCP endpoint

Scopes

Tokens and approvals are limited to scopes granted at issue time. The currently published, requestable scopes are:

• abn:lookup
• gst:status
• assets:receipts
• exports:write
• opportunities:read
• mcp:account.receipts

The following legacy contract tokens are reserved for future compatibility only. They may appear in the public OpenAPI contract, but they are not advertised in OAuth metadata, requestable, grantable, or accepted by current DCR flows, and a credential, account, plan, or future token does not unlock the unavailable capability:

• ppsr:search.org — future organisation PPSR permission; unavailable
• ppsr:search.serial — future serial-number PPSR permission; unavailable
• assets:monitor — future entity and asset monitoring permission; unavailable

Human dashboard sign-in

Human account pages use browser sessions. REST and CLI calls use an API key; MCP calls use an OAuth-issued scoped token. Keep machine-client credentials separate from browser sign-in state.