Concepts

Workspaces

Everything belongs to a workspace (an organization): domains, API tokens, the wallet, the activity log, and the contact book. A user can belong to several workspaces and switch or create them from the dashboard sidebar. API tokens are bound to one workspace — a token can never see another workspace's data.

Contacts

Every domain names a contact in each of four registry roles — registrant (the legal owner, shown in whois), admin, technical, and billing.

A workspace keeps a contact book (dashboard → Contacts) and points domains at entries from it. One entry is the default: it's used for all four roles on new registrations and transfers. Admin, technical and billing can be reassigned per domain from the domain's Contacts tab. The registrant can be changed too, but it is a different kind of operation: a registry trade that changes who legally owns the domain. It is priced from the TLD's trade fee (trade in GET /api/v1/tlds, 0 on most TLDs), confirmed at that price, and some registries email the new holder for approval or lock the domain against outbound transfers for 60 days afterwards. See Transfers.

A contact can be an individual or an organization (legal entity) with company and VAT numbers — use the legal entity when the domains belong to a company and billing should reflect it. Editing a contact updates the whois record of every domain already using it.

The wallet

Each workspace has a EUR wallet. Every purchase — registration, renewal, transfer — debits it. Money comes in by topping up (dashboard → Billing) or per-call pay-as-you-go (see Payments). If a registry operation fails after a pay-as-you-go charge, the credit stays on the wallet and the retry doesn't re-charge your card — no refund round-trips.

Some workspaces are on invoiced (postpaid) billing by arrangement: purchases accrue against the wallet and are invoiced monthly instead of requiring an upfront balance.

Explicit price confirmation

Every spending call requires confirm_price — the total you saw quoted. The server re-resolves the live price and refuses on any mismatch (409 price_changed, carrying the current price). This is the core agent-safety contract: an agent can never be surprised by a charge, and a stale quote can never silently spend more than intended.

Destructive operations have the same explicitness: deleting a domain requires naming it again, and the CLI refuses spending/destructive verbs without explicit flags.

API tokens

Tokens look like ingram_live_…, are stored hashed (shown once at mint time), carry a scope (read or write), and authenticate REST and MCP via Authorization: Bearer. Mint them at signup (POST /api/v1/accounts) or in the dashboard (Settings → API tokens).

The four surfaces

All four hit the same domain logic with the same safety contract; nothing is dashboard-only except viewing invoices and topping up by card.