Authentication

Protected endpoints require an API key, passed as a bearer token. A key carries a scope — the set of universes it can read and whether it may use the API and MCP at all — and the server enforces that scope on every request. See the Changelog for the cutover note if you integrated while the API was open.

Passing your key

Send the key in the Authorization header using the Bearer scheme:

curl https://api.bytetree.io/api/assets \
-H "Authorization: Bearer YOUR_API_KEY"

The same header works for every protected endpoint and for every response format (json, csv, toon).

Obtaining a key

API keys are issued through your ByteTree.io account; each key is minted with a scope that matches your subscription. Treat a key as a secret — it grants the access its scope allows, with no further sign-in.

Scope

Every key has two orthogonal scope dimensions:

Dimension	Values	Meaning
`universes`	array of universe slugs	Which universes the key may read. Reads outside this set are rejected.
`capability`	`view` \| `api+mcp`	Whether the key may call the REST API and MCP at all. `view` is for in-product viewing only; `api+mcp` is required for any programmatic access.

A view-only key is rejected from the API and MCP — it has no programmatic access regardless of its universe set. A key scoped to a subset of universes sees only those universes: a request for an out-of-scope universe returns 403, and list endpoints return only the in-scope rows.

Universe paths (/api/universes/:universe/…) take the customer universe slug — macro, public-50, global-trends-200, and the portfolio slugs. Use those names; internal engine aliases are not accepted. See Universes for the full vocabulary.

Errors

Authentication and scope failures return a JSON error envelope:

{ "error": "<message>" }

Status	When
`401 Unauthorized`	No key supplied, or the key is unknown / revoked / malformed.
`403 Forbidden`	The key is valid but its scope does not permit the request — a `view`-only key calling the API/MCP, or a request for a universe outside the key’s `universes` set.

The distinction matters when debugging: a 401 means the key itself was not accepted; a 403 means the key was accepted but the requested resource is out of its scope.

Which endpoints require a key

Every endpoint in this documentation requires a key, with one exception:

GET /api/health — liveness check, always open.

The universe endpoints (/api/universes/:universe and below) additionally enforce per-universe scope on top of the key check: a valid key whose universes set does not include the requested slug receives a 403.