Authentication

The Haszno API uses different authentication mechanisms depending on the endpoint and deployment type. This page explains each one and what it allows today.

Mechanisms at a glance

Public demo — no credentials needed

A set of GET endpoints return synthetic demo data without any credentials. If you omit the Authorization header entirely, the response is served unauthenticated. If you send an Authorization header, the request goes through the HTTP Basic wall instead: invalid credentials get 401, and a valid Basic header returns the deployment's shared dataset rather than the synthetic data.

Endpoints available without credentials on https://haszno.com Public Read-only:

The /api/settings and /api/impact responses include a "demo": true field. Other demo endpoints (categories, products, suppliers, stats, orders, proposals, peers, import-list) do not include this flag.

HTTP Basic auth — protected demo access

The hosted demo at https://haszno.com has an outer authentication wall that protects endpoints not on the public list above, except a few that carry their own protection, such as the account and session endpoints. This wall uses HTTP Basic auth.

Credentials Protected:

username: demo
password: <contact the Haszno team>

This is a shared credential for the demo deployment. It is not per-shop and not a production API. Contact the Haszno team to receive the password.

Send the credential as a standard Authorization: Basic header:

curl --fail-with-body \
  --user 'demo:<password>' \
  'https://haszno.com/api/rules'

Or with the HASZNO_BASIC environment variable used by the CLI and MCP server:

export HASZNO_BASIC='demo:<password>'
haszno rules list --json

With HTTP Basic access you can call all endpoints that require authentication, including write operations (order ingestion, rule management, feed imports, settings updates).

API Bearer tokens

API Bearer tokens are designed for agents, CLI, and MCP server access. They are the intended long-term mechanism for per-shop programmatic access.

Token format

Tokens are issued as haszno_<43 characters>, where the 43 characters are base64url (A–Z, a–z, 0–9, -, _). The full string starting with haszno_ is the token value you send.

Authorization: Bearer haszno_<your-token>

Creating a token

1. Register an account at https://haszno.com (via POST /api/auth/register) or log in (POST /api/auth/login). Both return a session cookie.
2. With the session cookie, call POST /api/auth/tokens with a JSON body {"name": "…", "scope": "read"} (scope is read or write, default read) to issue a token.
3. Copy the token field from the response — it is shown exactly once and stored only as a hash.

You can also list active tokens (GET /api/auth/tokens) and revoke them (DELETE /api/auth/tokens/:id) with the same session cookie. A Bearer token cannot be used to manage tokens; these three endpoints accept only the session cookie.

What Bearer tokens work for today

Planned: per-shop Bearer tokens on haszno.com once multi-tenancy is out of developer preview.

x-api-key — self-hosted only

On a self-hosted Haszno instance, you can set HASZNO_API_KEY as an environment variable. All requests that include this value in the x-api-key header or as a ?api_key= query parameter are accepted without a session.

This mechanism is not active on haszno.com. The environment variable is not set on the hosted deployment.

Keeping credentials safe

• Store credentials in environment variables, not in source code or committed config files.
• Use HASZNO_BASIC for the demo password and HASZNO_API_KEY for the API key. The CLI and MCP server read these automatically.
• Run haszno login to save credentials to ~/.config/haszno/config.json (created with chmod 600). Both the CLI and MCP server read from this file.
• Never pass a credential as a command-line argument in a shared shell environment — it appears in ps output and shell history.
• List active tokens with GET /api/auth/tokens; revoke unused ones with DELETE /api/auth/tokens/:id.

Error responses

Error bodies always follow the shape { "error": "Hungarian error message" }. See Errors and rate limits for the full error reference.