URL: /concepts

---
title: Concepts
description: The vocabulary the rest of the docs assumes you know.
---

## Account, organisation, member

You sign in as a **user**. Every action runs inside an **organisation** (org). That's where domains, billing, and contacts live. A solo account is a one-member org under the hood.

A user can belong to multiple orgs. Each membership has a **role** — `owner`, `admin`, or `member`. Some operations require admin or owner.

Org identifiers are opaque strings prefixed `org_`. You'll see the OID in URLs and tool calls. Don't parse it.

## Domain states

| State | Meaning |
| --- | --- |
| `pending` | We've requested registration; the registry hasn't confirmed yet. |
| `registered` | Live — the domain resolves and we own it on your behalf. |
| `expired` | Past expiry, in the registry's renewal grace window. Still recoverable. |
| `redemption` | Past grace, in redemption. Costs more to recover; clock is ticking. |
| `external` | The domain belongs to your org but is at another registrar (used for transfer-out tracking). |
| `deleted` | Released to the registry pool. |
| `failed` | Registration attempt failed; see `last_error`. |

`auto_renew` and `expiry` belong to all live states.

## Contacts and roles

A **contact** is a reusable address record (name, address, phone, email). On a registered domain you can assign up to four roles:

- `registrant` — the legal owner.
- `admin` — receives administrative notifications.
- `technical` — receives technical/abuse notifications.
- `billing` — receives renewal notices.

The same contact record can fill multiple roles, and one contact can be assigned to many domains. Changing a contact updates every domain that references it on the next sync.

## DNS management

A domain's `dns_management` is either `domaingenius` (we host the zone on Cloudflare and you edit records via the API/MCP/dashboard) or `external` (you point the nameservers somewhere else). Toggle with `update_domain_settings` or via the dashboard.

A **preset** is a bundle of DNS records that configure a common service (Vercel, Google Workspace MX, Microsoft 365, etc.) in one apply.

## Balance and funding

Each org has a prepaid **balance** in AUD cents. Registrations and renewals debit the balance. If `auto_topup_enabled` is on and the balance falls below the threshold, we charge the saved card to refill.

A **transaction** is an immutable ledger row — top-up, debit, refund, adjustment. The balance is the running sum.

## API keys and scopes

A **key** is a bearer token (`dg_live_...` or `dg_test_...`) with one or more **scopes**. A scope is a verb on a resource: `domains:read`, `dns:write`, `contacts:write`, etc. A key with `dns:read` cannot edit DNS, even for a domain it can see.

Scopes are checked at the interface layer (the MCP tool body, the API route handler). The shared business logic underneath trusts its inputs.

## Confirmations (agent actions)

Anything an AI agent does that spends money or makes a bulk change runs through the **confirmation pipeline**. If the action exceeds the user's threshold or involves ≥5 items, the response is `status: "pending_confirmation"` with a token and an approval URL. The user approves out-of-band; the agent retries the call with the same `request_id` to execute.

It's the thing that stops an over-eager assistant from registering 200 domains because you said "and a few alternates".

## TLDs and eligibility

Australian (`.au`) TLDs have registry eligibility rules — `.com.au` and `.net.au` need an ABN/ACN and a name that matches it; `.id.au` is for individuals; `.org.au` for non-profits. We pass eligibility data to the registry on your behalf. Use `get_tld_info` (MCP) or `GET /pricing/{tld}` (API) for the current rules.

## Sync

State you change locally — auto-renew, contact assignments, privacy — is queued and applied to the registrar on the next **sync** cycle, not synchronously. Some changes (registration, renewal, DNS records) are synchronous; the docs note which.