Registering a New Data Lake

New here — no tenant, no API key yet? You create your own Data Lake from the command line with dlake register (self-service onboarding against the standalone Registration API). Signing up itself has no in-app or MCP surface — a remote MCP connection is always tenant-scoped, so it can’t exist before you’ve registered — but once your Data Lake is seeded and you hold a key, the rest of the wizard is available over MCP (see Finishing the wizard from an AI client below). The flow is three verbs and two emails:

1. dlake register start --email <e> --company <name> --phone <tel> --consent-crm-backup --consent-erp-backup --consent-phone creates the account and emails you a verification link. The three affirmation flags are required — the two backup flags confirm the registrant has made their own backups of their CRM and ERP data (a guarantee by the registrant, not a request for Commercient to make backups), and --consent-phone consents to phone contact. The server refuses start without all three; they are the registrant’s decision, so agents must ask the human rather than pass them unprompted. --document-sync (optional) marks a File-Sync-only account. --instance-type follows from what type of setup this is: an integration (CRM/ERP syncing through the platform) takes the customer’s real ERP (e.g. SAGEINTACCT), so the CRM and connector setup match the ERP from the start; a standalone Data Lake (no integration) omits it, and the Commercient Data Lake default (machine code COMMERCIENTDATALAKE) is the correct choice there, not a fallback. The accepted values are a server-side catalog: dlake register erps (anonymous, so it works before you have an account) lists them as a name/code table, and --instance-type takes either — the machine code or the display name, case-insensitively. start resolves what you typed to the code before it posts; a value that is not in the catalog is refused rather than registered against the wrong ERP (the server rejects it with code erp_unknown). The Data Lake is created either way. The portal password comes from a hidden prompt, or piped in with --password-stdin; it is never passed as a plain --password flag. Start saves a local pending record (userId + a 72h registration token), so the later verbs need no flags.
2. Click the verification link in that first email. Nothing provisions until you do. The link opens a small page hosted by the Registration API itself (…/api/Registration/Verify?uid=…&token=…) — there is no website to sign into and nothing to copy; clicking it is the whole step, and clicking it twice is harmless. The backend then creates your account and automatically seeds the Data Lake (DLO schema, Data Engine, routing).
3. When seeding finishes you get a second email — the Data Lake welcome email — carrying your tenant owner’s temporary password for the web app. Log in and change it. Those two emails are the whole human journey.

Polling. dlake register status (add --watch to loop) reports emailVerified → isProvisioned → dataLakeSeeded. It authenticates with the registration-scoped bearer that start returned — valid 72 hours and bound to that one userId, so it can poll and claim only its own registration. start saved it locally, so you never handle it.

For agents / CI (headless): dlake register status --watch polls until seeding completes and prints a once-only bootstrap API key — a 7-day, full owner-admin key — auto-saved into a dlake profile so every other dlake command (and MCP, via key exchange) works immediately. It is shown once; store it now.

What the bootstrap key unlocks (do this next). Because it is an owner-admin key, the moment register status hands it over the same CLI drives both planes with no further login:

dlake tool list                    # data plane: read/write records, query, export, aggregate, time travel
dlake admin list                   # control plane: DAB config plus the whole DDL surface
dlake admin create_schema --schemaName sales
dlake admin create_table --tableName PizzaOrders --columns @columns.json

See Admin Control Plane and Command-Line Interface (dlake) below for the tool catalogues and the argument conventions. Headless recipe: let the CLI mint a conforming portal password with dlake register start --generate-password --email … --company … --phone … --consent-crm-backup --consent-erp-backup --consent-phone (affirmation flags only after the human has agreed), then dlake register status --watch. KEEP the printed password: register login and portal login both need that exact string and it is stored nowhere. The portal password must be 8-32 characters made only of letters, digits and ! # $ % & * ? @ _, with at least one uppercase, one lowercase, one digit and one of those specials; register start refuses anything else and NAMES the offending characters, so a wrong one is caught before it is submitted. Any other character - including . - + / = quotes, brackets and space - is outside the set, so do not synthesise a password from an arbitrary byte encoding: --generate-password always produces a conforming one. To choose your own instead, pipe it with --password-stdin. (That password is only the portal password, recoverable later by mail-back; the credentials that matter — the welcome-email temp password and the bootstrap key — never pass through the agent.)

Lost the verification email? dlake register resend re-sends the same link.

Picking a registration back up — dlake register login. The registration token start saved is valid 72 hours and lives on the machine that ran it. On a different machine, or after it expires or is lost, run dlake register login --email <you@example.com>: it exchanges your email and the password you chose at start for a fresh registration token, saves it locally, and reports the wizard step you’re on — so status and resend work again with no flags. The password comes from a hidden prompt or --password-stdin (as at start, a plain --password flag is refused). Don’t run start again — a second start on the same email is a duplicate-email failure by design; login is the resume path.

Finishing the wizard from an AI client (steps 3 to 5). The remaining wizard steps — recording your server IP (step 3), connecting your CRM (step 4) and choosing the ERP connector, then provisioning (step 5) — no longer need the browser. Once your Data Lake is seeded you have an API key, and that key drives the registration_* tools on the Admin Control Plane (see that section below): ask your agent for registration_state first — its CurrentStep says which step you’re on and therefore which tools apply. If the wizard has not passed step 3 yet, run registration_capture_server_ip with your server or public IP — the CRM step is guarded on it. Step 4 is registration_crm_catalog → registration_crm_select → registration_crm_connect → registration_crm_finalize (with four registration_crm_oauth_* tools for OAuth-based CRMs — see Connecting an OAuth CRM below for which of the two callback legs applies); step 5 is registration_connector_catalog → registration_connector_submit → registration_connector_provision, then poll registration_provisioning_status. Credential values you hand these tools are never logged or written to the audit trail — only the field names are.

Connecting an OAuth CRM (step 4). OAuth CRMs have two callback legs, and the CRM’s callbackMode in the catalog says which apply: loopback (the CLI listens on 127.0.0.1:8801-8803), website (the platform receives the callback on its own public endpoint), or both — you pick per handshake. The choice is simply where the browser can reach: use the loopback leg when the person authorizing is at the machine running dlake (dlake registration oauth --crm <Crm> does start → listen → complete in one command), and the website leg when they are not — start with no redirect URI (dlake registration oauth --crm <Crm> --no-browser), have them approve in any browser on any network, then poll registration_crm_oauth_status until it reports code_received and finish with registration_crm_oauth_complete --state <state>. On the website leg you do not pass a code: it was delivered to the platform, which reads it from the parked attempt (status never returns it). HubSpot uses the website leg, because its per-ERP apps register the platform’s callback rather than the CLI’s loopback ports. Salesforce, Zoho, HubSpot and Klaviyo then end with a PIN emailed to the registration address — nothing displays it on screen — which you confirm with registration_crm_oauth_confirm_pin. A handshake is single-use and expires 30 minutes after it starts; re-run the start to get a fresh one.

Hosting — where your gateway database lives. Every Data Lake has a gateway database, and the hosting says where it lives: express, a SQL Server 2025 Express container dedicated to you on a container host, provisioned when your Data Lake is seeded. express is the default — a registration that chooses nothing is express. Record it yourself with registration_hosting_set (or dlake registration hosting set express) and registration_hosting_get will report it as an explicit choice rather than a default. The choice is locked once your Data Lake is seeded — after that the set call is refused with hosting_locked, so make it while you are still registering. An installation with no container hosting refuses express with hosting_unavailable, and a value it does not accept comes back as hosting_invalid. For an express tenant the read also reports the container’s state — provisioning, ready, failed or removed — and the host and port it answers on once it is ready.

Changing your ERP at step 5. Your registration starts out on the Commercient Data Lake ERP. Submitting the connector configuration is also where you can change it: supply an ERP name with the connector config (erpName on the connector submit, in the portal or over MCP) and it replaces the registration’s ERP before the configuration is saved, so the connector catalog’s fields and the Connection Manager record name follow the new one. Leave it out and your existing ERP is kept. The CRM was always changeable the same way at step 4 — just re-select it.

Hand-off. Once the bootstrap key is saved (agent) or you’ve logged in with the welcome-email password (human), you’re in the normal login/key world — generate longer-lived keys under Settings → API Keys, use dlake login, and connect MCP. See Command-Line Interface (dlake) below, and the API Usage Guide’s Registration section for the REST contract.