Public API (ah_live_)

✅ Verified

Against Axowl.Auth/EndPoints/PublicApiEndpoints.cs — 2026-08-07. The endpoint inventory is no longer maintained by hand here; it is generated from the server (see below). Reference integration is Bullmark (BrandEndpoints.cs).

/api/public/v1 is the documented surface for external developers. It is versioned: the contract is stable and breaking changes go to v2.

The endpoint list lives in the spec, not on this page

Browse it: /scalar/public — every endpoint, its schema, and a Try it box you can fire a real request from. Machine-readable: /openapi/public.json — point your generator at this.

The spec is produced from the running server, so it cannot drift. This page used to carry a hand-written list and it had gone stale — six of the twelve live endpoints were missing from it. What stays here is the part a schema cannot teach: what ready means, why 401 is an outage and not an empty result, and where the gate belongs. The section below is a guided tour of the endpoints that need explaining, not an inventory.

Authenticate

X-Api-Key: ah_live_…

An Org API key identifies one organization and returns that org’s data only — never another org’s. Issue and rotate keys in Settings → Keys. Keys are SHA-256 hashed at rest and shown once.

A dead key must not look like an empty result

If the key is missing or revoked every call returns 401. Do not collapse that into “the user has no organization” — a wiped key once made an outage look like a user with nothing to link, and it took a day to spot. Treat 401 as an outage, not as data.

ready — existence is not usability

Every org DTO carries a ready boolean. It is the single most important field on this surface.

{ "id": "…", "name": "Acme", "slug": "acme", "ready": false }

	Meaning
ready: true	The org can sign. Safe to bind your resources to it.
ready: false	The org exists but cannot sign yet. Binding to it produces a shell that fails later.

Gate on ready, never on mere existence. An org that isn’t ready will accept your binding and then fail at the moment something has to be sealed — far from where the mistake was made.

How it is decided

ready = the org has an Org Master Seal
      AND its owner has registered a Personal Seal

Both halves are required. A corporation’s Master Seal is auto-issued at creation, so on its own it is always true and would never catch an owner who skipped sealing. The owner’s Personal Seal is the real signal.

What counts as a Personal Seal

The evidence is a credential with a bound key — the artefact the seal ritual actually produces. (Internally: UserCredential.KeyId. A User.PersonalSealKeyId column exists but is written by no live code path; a fix on 2026-07-27 stopped ready from reading it, which had made every org report ready: false regardless of whether its owner had sealed.)

The state your gate should show

Owning an organization and being able to use one are different things, and so are the messages:

Situation	Tell the user
No Axowl account at all	They need to become an account owner first — see The account-owner gate
Account, no org	Create an organization on Axowl
Org exists, ready: false	Setup isn’t finished — register the seal. Do not say “your organization was created” as if it succeeded
ready: true, already bound	Choose a different organization
ready: true, free	Proceed

Endpoints that need explaining

Not the full list — that is the spec. These are the ones where calling them correctly is not obvious from the schema.

List the orgs an email owns

POST /api/public/v1/orgs/by-owner
X-Api-Key: ah_live_…

{ "ownerEmail": "someone@example.com" }

Returns every org that email owns, each with ready.

[] is ambiguous here

An unknown e-mail and a known one that owns nothing both answer []. When the difference matters — and it does, because they need different words and different destinations — use /orgs/owner-status instead, which distinguishes them and takes the identity from a token rather than from a parameter.

Match one org by name

POST /api/public/v1/orgs/match
{ "ownerEmail": "…", "orgName": "Acme" }

Read one org by id

POST /api/public/v1/orgs/by-id
X-Api-Key: ah_live_…

{ "orgId": "8f3a…" }

Returns { id, name, slug, ready }. 404 means no such org.

Store the id, not the name

An org can be renamed on Axowl at any time, and nothing notifies you when it happens. Every other lookup on this surface is keyed by the org name — so once a rename lands, the name you saved no longer matches anything and you cannot look the org up to repair it.

Keep the id from whichever call first identified the org, and re-read through this endpoint when you display the name. The id never changes. If the call fails, keep showing the name you already have rather than blanking it — a slightly stale name reads better than no company name at all.

List an org’s app groups (brands)

POST /api/public/v1/orgs/app-groups
{ "ownerEmail": "…", "orgName": "Acme" }

Read one app group (brand) by id

POST /api/public/v1/app-groups/by-id
X-Api-Key: ah_live_…

{ "appGroupId": "1c9d…" }

Returns { id, orgId, name, description, iconUrl, brandColor }. 404 means no such group — it may have been deleted.

An App Group is the brand: the org is the company, and each App Group is one product or service line. If you are listing brands, read the name and branding from here instead of asking the customer to type them into a second form. Two hand-entered copies of one brand name drift apart the day either side is edited, and the customer has no way to tell which one is showing.

orgId comes back so you can confirm the group still belongs to the company you think it does, rather than trusting a binding you stored earlier.

Every App Group of that org — for partners that treat an App Group as a brand (the org is the company; an App Group is one product/service line, and its products live inside it). An empty list is a normal answer: an org may not use App Groups yet. First consumer: Bullmark’s “Select Your Brand (App Group)” dropdown.

The org behind the key

GET /api/public/v1/me

Import end users (migration)

POST /api/public/v1/end-users/import
X-Api-Key: ah_live_…

{ "appGroupId": "…", "source": "clerk", "sendInvites": false, "users": [ … ] }

Bulk-imports users exported from another auth provider (Clerk, Kinde, Supabase, Firebase, Auth0, NextAuth …) into one App Group — max 500 rows per request, each row answering independently (created / duplicate / invalid) with the new endUserId for your foreign-key re-mapping. Password hashes, when supplied, are stored dormant (provenance only — no login path reads them): imported users sign in passwordlessly with the same email. The full walkthrough per source platform lives in the Migration guides.

App-group-scoped keys import into their own group only

An ah_live_ key scoped to one App Group gets 403 app_group_scope_mismatch for any other appGroupId — same isolation rule as the rest of this surface.

Billing statements

GET /api/public/v1/invoices
GET /api/public/v1/invoices/{id}

Monthly invoices for the calling org. Axowl is prepaid — an invoice records what was charged and whether your credit covered it, never a balance due. Every line carries the ledger reference it was charged under, so amounts are verifiable independently of this API. See Invoices.

Re-check on the server

Treat anything a browser hands back as a claim. A user can navigate straight to your form without ever visiting Axowl, so re-run the same ready check server-side before you commit the work. This is the rule the payment flow already follows: the redirect is a hint, the server decides.