Authentication

Every API request must include a valid API key as a Bearer token in the Authorization header. Create and manage keys in Settings → Developer → API Keys inside your space.

API keys are minted by a space admin in Settings → Developer. Minting a key requires:

• A paid plan with the api-keys entitlement.
• The admin.write scope (a space admin role).

A key’s scopes are clamped to the scopes of the admin who created it — you cannot mint a key more privileged than yourself. Rotate or revoke a key from the same screen; a revoked key stops working within seconds.

All API keys follow a structured prefix format that makes them easy to identify and rotate:

mad_sk_a1b2c3d4e5f6...

Beyond scopes, some endpoints require plan-based entitlements. These control access to features that differ between the Starter and Pro plans. If your space does not have the required entitlement, the API returns 403 Forbidden with an entitlement_required error type.

Endpoints that run a paid AI model draw down your space’s monthly AI credit allowance. When the allowance (or the underlying USD budget) is spent, those endpoints return 402 with an ai_credits_exhausted error type. Credits reset at the start of each billing cycle.

Credit-billed operations include:

• Capture content scans— a photo is the cheapest; an audio or video clip costs more (transcription, plus a frame for video). Clip length is capped per plan, so the per-clip cost is bounded.
• Mirror Ask and transcription— billed by the tokens / audio they consume.

Routine embeddings and background enrichment (e.g. re-embedding a concept you edit) are included in your planand do not draw down credits. Exact credit weights are plan-dependent and can change between Starter and Pro — treat the relative ordering above as the contract, not a fixed number.

Each API key is assigned a set of scopes that control which endpoints it can access. Scopes follow a module.action pattern. Required scopes are documented on each endpoint in the API Reference.

If a request is missing a required scope, the API returns 403 Forbidden with a missing_scope field indicating which scope is needed.

The admin.read / admin.write scopes unlock space-administration endpoints (members, roles, branding, billing, API-key management) that are scope-gated but not part of this published v1 reference. They behave like every other endpoint — same auth, errors, and rate limits — but their request/response shapes are not yet documented here, so treat them as subject to change.