API reference

1. Get a credential. For your own back-office services, issue an API key (be_…) from the Developer page inside the hub. For a federated child tool, ask the hub owner for CORE_CHILD_APP_TOKEN__<TOOL> and CHILD_WEBHOOK_SECRET__<TOOL>.

2. Confirm access. Call GET /api/public/brands with the API key. You should get back the brand the key is scoped to, including its current identity_version.

3. Read the identity. From your backend call GET /api/public/v1/brand/by-id/:id/bundle with the child token and X-Tool-Slug header. Store the response in a brand_cache row keyed by brand_id, together with identity_version.

4. Stay fresh. Expose a webhook endpoint, verify X-Hub-Signature with CHILD_WEBHOOK_SECRET__<TOOL>, and mark the matching brand_cache row stale on identity.updated. Re-fetch the bundle with ?since=<cached version> on the next read.

API key (be_…) — issued per brand from the API keys tab. Use for your own services calling /api/public/* v0 endpoints. Always brand-scoped.

Federation token — short-lived HS256 JWT minted from a signed-in user's session via POST /api/public/federation/mint. Children present it to /api/public/federation/exchange to receive the user's brand context. Pass { brand_id } in the mint body to target a specific brand (recommended in multi-brand setups).

Child app token (CORE_CHILD_APP_TOKEN__<TOOL>) — long-lived secret used by a child's backend to call the v1 contract (bundle, events). Paired with the X-Tool-Slug header.

Every credential travels in the Authorization header as a Bearer token. Never place a credential in a query string, and never ship a child token or API key to the browser.

Every error response uses the same shape: { "error": { "code": "…", "message": "…" } }. Branch on code, never on the message text — messages are human-facing and may change.

Codes: bad_request (400), unauthorized (401), forbidden (403), not_found (404), rate_limited (429), server_error (500).

Retry policy: retry 429 after the Retry-After header, retry 5xx with exponential backoff capped at 30 seconds and at most 5 attempts, and never retry other 4xx responses — fix the request instead.

Successful responses keep their endpoint-specific shape; the envelope applies to failures only.

Default budget is 60 requests per minute per credential, with at most 2 concurrent requests. Exceeding it returns 429 with Retry-After.

Never poll the bundle endpoint on a timer without ?since=<cached version>. With the version parameter a no-change read is a cheap { not_modified: true }; without it you pull the full identity every cycle.

Event ingestion is per-event and idempotent. Batch client-side into 200–500 event chunks, send them sequentially, and always include an idempotency_key so a retry after a network blip cannot duplicate.

Persist your cursor or last-seen version only after your own transaction commits. A failed batch must leave the cursor where it was.

Prefer push over poll: subscribe to the identity.updated webhook and let it invalidate your cache instead of scheduling frequent reads.

Children call GET /api/public/v1/brand/by-id/:id/bundle?since=<version> from their backend. When since matches the current identity_version, the hub returns { not_modified: true } — the child clears its stale flag and serves the cached bundle.

On a 200 the body matches BrandBundleSchema. Children upsert into a brand_cache(brand_id PK, identity_version, bundle, stale, fetched_at) table — ONE ROW PER BRAND. Never collapse to a singleton.

The bundle carries two top-level design blocks alongside the identity document. colors = { source, palette[] } where every entry has id, name, role (primary | secondary | accent | neutral | background | text | success | warning | danger), hex (canonical, lowercase #rrggbb), rgb { r, g, b } (derived), usage and locked. Locked entries are admin overrides and never change on regeneration — treat hex as the source of truth and derive any other colour space yourself.

logos = { items[], rules[] }. Each item has variant (logo_positive | logo_negative | symbol | wordmark | favicon | other), label, usage, background, clear_space, min_width_px, asset_id and a signed url (30 min TTL) plus mime. Re-fetch the bundle rather than hot-linking an expired URL, and pick logo_negative for dark surfaces.

Editing a brand's identity bumps identity_version and enqueues a delivery in child_context_deliveries for every matching child_context_subscriptions row. A scheduled job hits POST /api/public/v1/internal/dispatch-tick every minute; the hub POSTs identity.updated to each child with X-Hub-Signature (HMAC-SHA256 over the raw body, secret per child).

Children verify the signature with CHILD_WEBHOOK_SECRET__<TOOL>, mark the matching brand_cache row stale = true, and return 200 fast. The next bundle read refreshes the cache.

Deliveries retry with exponential backoff. Your endpoint must be idempotent: the same identity.updated may arrive more than once.

A user can be a member of multiple brands (memberships table). Each user has one active brand at a time, persisted in user_active_brand. The hub mirrors the active brand slug to a .thebrandengine.ai cookie (be_active_brand) so every child subdomain knows on boot which brand the user is on.

Child responsibility: read the be_active_brand cookie, mint a federation token with { brand_id }, and key every cache + query by that brand id. When the cookie changes (focus event or BroadcastChannel), re-mint and refetch.

Subscriptions are keyed (brand_id, tool_slug) — a new brand gaining an entitlement auto-creates its subscription via DB trigger, so identity webhooks flow without manual setup.

Where to find a Brand ID: sign in to the hub and open Developer → API keys → Brands & IDs. Every brand you are a member of is listed there with its UUID and slug, with a copy button. The active brand's ID is also shown in the Brand page header.

Pairing keys with brands: an API key row stores brand_id, so a key only ever resolves one brand. To connect a second brand to the same tool, switch brands in the sidebar switcher, issue a new key, and send that key with the matching Brand ID (or the X-Brand-Id header where the endpoint accepts it).

Listing brands: from a child, call GET /api/public/brands/me with the user's federation token to render a brand switcher; from a back-office integration, call GET /api/public/brands with the API key (returns the single brand the key is scoped to).

Use the brand-ecosystem-contract skill from the child project's chat, or follow the README at src/lib/ecosystem-contract/v1/README.md.

Copy the schemas and webhook helpers verbatim — they must stay byte-identical to the hub.

Machine-readable contract: GET /api/public/v1/docs/openapi.json. Human reference: /developers/reference. PDF export: /api/public/v1/docs/api.pdf.