Skip to main content
A handle is the public identifier for a Marfa account. The same string serves two roles:
  • Account username. Every Marfa account has a handle. Required at signup, unique per Marfa instance, used in URLs, in the marketplace, anywhere identity surfaces publicly.
  • Publisher handle. When the account publishes types, those types live in the handle’s namespace: <publisher>.<type>. No separate claim — the username is the publisher handle.
Reservation rules apply at signup. Squatting is prevented before publishing is possible.

​
Username convention

Examples that pass: august, readwise, carla, me-cayzer, acme-co. Examples that fail: -carla, carla-, carla--co, ab (too short), MyHandle (uppercase).

​
What’s reserved

Three categories of handle cannot be claimed:
  • Reserved roots. core, system, app, user, marfa. These root names belong to the platform’s namespace tiers — claiming them as handles would corrupt the type-identifier grammar.
  • Reserved structural words. Common-meaning words (admin, api, support, help, docs, console, auth, login, register, settings, dashboard, billing, terms, privacy, about, home, plus pronouns and similar literals). Pre-claimed against squatting and to keep ordinary URLs and surfaces unambiguous.
  • Reserved brand names and future-platform namespaces. Major tech companies and consumer apps (google, apple, microsoft, obsidian, notion, figma, etc.) plus names plausibly needed for future platform-shipped namespaces (sync, auth, data). Pre-claimed to prevent confusion-by-impersonation.
Attempting to claim a reserved handle returns 400 handle_reserved. Trademarks and offensive terms beyond the reserved list are handled via takedown or dispute on demand. The reserved-handles list is maintained in the platform repository and reviewed before public release. Coverage tightens over time; once published it does not loosen.

​
Domain verification

A publisher can verify a domain to gain a verified-publisher badge. The badge sits next to the handle in the marketplace and console; it does not create a parallel namespace. august.meal_plan and me.cayzer.meal_plan do not coexist as different things — the verified-domain badge displays alongside the existing handle, and the type identifier stays singular.

​
Handle change policy

Handles are practically immutable. Once claimed, they don’t change. Manual support-led rename for genuine exceptions. Architecturally, the handle is separate from the underlying user-id. Internal references (audit trails, admin records, federated metadata) key off the immutable user-id. The handle is the public-facing label and could be renameable in the future without touching the foreign references. When demand for renames justifies it, the marketplace will support GitHub-shaped redirects: a renamed handle redirects to the new handle for a grace period; new types use the new handle; old types stay or migrate lazily; the old handle releases for re-registration only after the grace period expires.

​
Account deletion

Deleting a publisher account triggers two behaviors:
  • Published types stay live, marked orphaned. Consumers don’t lose access to types they’ve already installed. The registry continues to list them; new installs are still possible but warned.
  • The handle locks for ~1 year. It cannot be re-registered during that window. This blocks impersonation — re-claiming a deleted handle and pretending to be the original publisher.
Existing spaces that installed the publisher’s types are unaffected by the handle lock. The schema is already copied into their space; orphaning only stops new updates from the original.

​
Why a single global namespace

The handle namespace is global for discovery, not for lock-in. Same shape as GitHub or npm — a global namespace exists to make discovery work, not because it’s the only place types can live. Self-hosters can use the central registry, mirror it, or skip it entirely. Schemas are inspectable and portable; a type is just a schema, you can extract it, modify it, register it elsewhere. Pure-local users never touch the central service. The global handle namespace is the price of network effects, not a precondition for using Marfa.