# Building with agents (/docs/agents) BWEZE is built to be driven by AI agents as much as by humans. ## CLI - `@bweze/cli` [#cli---bwezecli] Agents drive BWEZE from the terminal the same way people do: ```bash npx @bweze/cli login bweze projects create acme-web --type frontend bweze projects domains search acme ``` Anything the CLI does is also a plain REST call with a bearer key; see the [error contract](#error-contract) below. Calls that spend money or send a message accept an idempotency key, so a retry never double-acts. ## SDK - `@bweze/messaging` [#sdk---bwezemessaging] ```ts import { BwezeMessaging } from "@bweze/messaging"; const sms = new BwezeMessaging({ apiKey: process.env.BWEZE_API_KEY! }); await sms.send({ to: "+250788123456", template: "Code {{c}}", data: { c: 1234 } }); ``` Errors throw a typed `BwezeError` carrying the same `code` and `docs` URL as the HTTP API. ## Agent-readable docs [#agent-readable-docs] * [`/llms.txt`](/llms.txt) - the index, one screen. * [`/llms-full.txt`](/llms-full.txt) - everything an agent needs in one file. * Every docs page is also served as raw markdown under `/llms.mdx/docs/...` for tools that want per-page context. * Machine-readable API spec: `https://api.bweze.com/v1/openapi.json`. ## Error contract [#error-contract] Every error, everywhere: ```json { "error": { "code": "insufficient_balance", "message": "...", "docs": "https://docs.bweze.com/errors/insufficient_balance" } } ``` Always branch on `code`; `message` is for humans. Common codes: | Code | Status | Meaning | | --------------------------------------- | ------ | ---------------------------------------------------------------------- | | `missing_api_key` / `invalid_api_key` | 401 | No or bad bearer key | | `secret_key_required` | 403 | Endpoint needs `bw_sk_...` | | `key_role_denied` | 403 | The token owner's workspace role doesn't allow this action | | `token_permission_denied` | 403 | The token was not granted this action ([API tokens](/docs/api-tokens)) | | `token_resource_denied` | 403 | The project, backend or zone is outside the token's resources | | `token_ip_denied` | 403 | The request's address is outside the token's IP filter | | `token_expired` / `token_not_yet_valid` | 401 | Outside the token's validity window | | `insufficient_balance` | 402 | Top up before retrying | | `recipient_opted_out` | 409 | Never retry | | `idempotency_key_reuse_mismatch` | 409 | Same key, different content | | `message_too_long` | 400 | Over 10 segments | # API tokens (/docs/api-tokens) Every call to the BWEZE API carries a token: ```bash curl https://api.bweze.com/v1/me -H "authorization: Bearer bw_sk_..." ``` A token does only what you granted it, on the resources you gave it, from the addresses you allow, while it is valid - and never more than its owner's role in the workspace. Make one per job (a CI pipeline, a server that sends SMS, a script that edits DNS) so each can be narrowed, rolled or revoked on its own. Manage them in BWEZE Platform under **Manage workspace › API tokens**. ## Create a token [#create-a-token] 1. **Start from** a template, or a blank custom token: | Template | Grants | | --------------- | ------------------------------------------------------------- | | Read everything | `deployment:read`, `backend:read`, `dns:read`, `message:read` | | Deploy from CI | `deployment:read,create,update`, `backend:read,create` | | DNS editor | `dns:read,create,update,delete` | | Send SMS | `message:read,send` | 2. **Permissions and limits.** Name it, choose its owner and type, then: * **Permissions**, per product: no access, read, or edit (send for SMS, run commands for Terminal). Open a product to pick single actions. Anything your role cannot do is shown but locked. * **Resources**: all projects, backends and DNS zones, or only the ones you tick. A token limited to some projects cannot create new projects; the same goes for backends and zones. * **Client IP filter**: IPv4 and IPv6 addresses or ranges, one per line. Empty allows any address. * **Validity**: an expiry (30 days, 90 days, 1 year, a date, or none) and optionally a start time. 3. **Review** the summary and create it. The secret is shown **once** - BWEZE keeps only a hash. ## Permissions [#permissions] | Product | Actions | What they allow | | ----------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- | | Deploy (`deployment`) | `read` `create` `update` `delete` | Projects, services and their settings (`update`), job runs (`read`), cron jobs, firewall rules, analytics | | Backends (`backend`) | `read` `create` `delete` | Backend stacks; `create` also starts them and reads their connection keys | | Domains and DNS (`dns`) | `read` `create` `update` `delete` | Zones and records, custom domains, domain search and registration | | SMS (`message`) | `read` `send` | Previews; sending is charged to the wallet | | Terminal (`terminal`) | `exec` | Run commands in a project's container, and run or stop one-off jobs on a service | Tokens can never manage the workspace, its members, billing or other tokens. Publishable tokens (`bw_pk_...`) are for browsers and apps: they can only read. ## Who a token belongs to [#who-a-token-belongs-to] * **You** (the default): it can never do more than your current role allows. Each request checks the token's grant **and** your live role, so if you are demoted it loses those rights on the next request, and if you leave the workspace it stops working (`token_owner_removed`). * **The workspace**: for automation that must outlive any one person. It keeps working when people leave. Only owners can create, widen or roll one, and it is capped by the owner role. ## Change, roll and revoke [#change-roll-and-revoke] Open a token to see what it can do, when it was last used and from where, and its activity: every create, edit, roll and revoke, with who did it. * **Edit**: narrowing (fewer permissions or resources, a tighter IP filter, an earlier expiry) is open to the token's owner and to workspace owners and admins. Widening takes what creating takes: only the token's owner, within their role (owners, for a workspace token). * **Roll**: a new secret with the same permissions; the old secret stops working at once. * **Revoke**: the token stops working at once and stays listed as revoked. ## Check a token [#check-a-token] `GET /v1/me` returns the token's workspace, owner, permissions, resource scope and expiry: ```json { "keyName": "GitHub Actions deploy", "tokenId": "6f1c…", "organizationId": "…", "ownerKind": "user", "role": "developer", "tier": "secret", "permissions": { "deployment": ["read", "create", "update"], "backend": ["read", "create"] }, "scope": { "projects": ["…"], "backends": null, "zones": null }, "expiresAt": "2027-11-14T12:00:00.000Z" } ``` `null` in `scope` means every resource of that kind. ## Errors [#errors] None of these succeed on retry: change the token, or use another one. | Code | Status | Meaning | | ------------------------------ | ------ | ---------------------------------------------------------------------------------------------------- | | `token_ip_denied` | 403 | The request came from an address outside the token's IP filter | | `token_not_yet_valid` | 401 | Before the token's start time | | `token_expired` | 401 | After the token's expiry | | `token_owner_removed` | 403 | The member who owns the token left the workspace | | `token_permission_denied` | 403 | The token was not granted this action | | `key_role_denied` | 403 | The token was granted it, but its owner's role no longer allows it | | `token_resource_denied` | 403 | The project, backend or zone is outside the token's resources, or a scoped token tried to create one | | `token_policy_missing` | 401 | The key has no token policy; create a new token | | `publishable_key_write_denied` | 403 | A `bw_pk_` token tried to change something | ## How the client IP is known [#how-the-client-ip-is-known] `api.bweze.com` is served through Cloudflare. Cloudflare's edge sets the `CF-Connecting-IP` header to the address that connected to it and replaces any value a client sends, so it cannot be forged through the edge. BWEZE checks the IP filter against that address only, never `X-Forwarded-For`. A request that reaches BWEZE without a trusted address is refused by any token that has an IP filter. # Billing (/docs/billing) Each workspace has a **prepaid wallet in RWF**. There are no invoices to chase: you top up, usage meters as you go, and spending stops at zero. ## Top-ups [#top-ups] Top-ups arrive by mobile money: a push lands on the payer's phone, the callback settles, the wallet is credited, and a ledger entry is written. A double-delivered payment webhook credits the wallet **exactly once** - settlement is idempotent by design. ## Metering and settlement [#metering-and-settlement] Usage (for example SMS segments) is metered per action and debited by aggregation, keeping the zero-balance gate tight. Every send also takes a short-lived **balance hold**, so concurrent sends can't spend the same money twice and the wallet can never be driven negative between settlements. ## Domains [#domains] Buying a domain takes its price for the first year from the wallet at once (see [Domains](/domains) for the prices). If the domain cannot be registered, the full price goes back to the wallet. ## When the wallet is empty [#when-the-wallet-is-empty] * SMS sends return `402 insufficient_balance` with the cost and available balance in the message. * Domain purchases return `402 insufficient_balance` with the price and the available balance, and charge nothing. Both are signals to top up - retrying without a top-up will keep failing. # Deploy from Git (/docs/deploy) BWEZE deploys your app straight from a Git repository - frontend, full-stack, or API - and serves it on a public `bweze.app` URL. It's your app, your repo, your workspace: every workspace connects its own GitHub and deploys its own code. ## Deploy a public repo [#deploy-a-public-repo] No setup, no connection needed. 1. In the dashboard, open **Deploy**. 2. Paste a public GitHub URL (e.g. `https://github.com/you/app`). 3. Pick a build pack: * **Nixpacks** - auto-detects the framework (Next, Node, Python, Go, …) and builds it. * **Static** - a plain SPA / static site. 4. Click **Deploy**. In a minute your app is live at `https://-.bweze.app`. ## Choose a service type [#choose-a-service-type] On the Configure step, pick what the repo runs as. The type is fixed once the service exists; to change it, create a new service from the same repo. | Type | What it is | Reached at | | --------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | **Web service** | An HTTP server, public over HTTPS. | `https://-.bweze.app` and your custom domains | | **Private service** | An HTTP server only your workspace's other services can reach: an internal API, a cache front. | `http://app--` from those services | | **Background worker** | A process that runs all the time and listens on no port: a queue consumer, a bot. | Nowhere: it reaches out, nothing reaches in | | **Cron job** | A command run on a schedule. Nothing runs between runs. | Nowhere | Web and private services listen on the port in `PORT` (3000 unless you set another). Only web services get PR previews and custom domains. ## Commands [#commands] Every service can set: * **Start command**: replaces the image's own command (`CMD`), for example `node dist/worker.js`. A cron job's command is what each run executes. * **Pre-deploy command**: runs once on each new release before it goes live, for example `npm run migrate`. If it fails, the deploy fails and the release that was live stays live. It is stopped after 30 minutes, and a rollback does not run it again. Commands run as `/bin/sh -c ""` after the image's `ENTRYPOINT`, with the service's environment variables, so the image needs a shell. Change them under the service's **Settings**; they apply from the next deploy. ## Jobs and cron jobs [#jobs-and-cron-jobs] From a service's **Jobs** panel you can run a command once on its live release (a database backfill, a one-time script): it gets a new instance with the same image and environment variables, is stopped after an hour, and keeps its logs. Up to three jobs run at once per service. A cron job's schedule has five fields in **UTC** (`minute hour day-of-month month day-of-week`), for example `0 2 * * *` for 02:00 UTC (04:00 in Kigali) every day. A run is stopped at its time limit (one hour unless you set another, twelve at most), and a run never overlaps the previous one: if it is still going when the next is due, that one is skipped and listed as skipped. Jobs, cron runs and pre-deploy commands are billed like the service while they run, for their memory and CPU. ## From the CLI and the API [#from-the-cli-and-the-api] ```bash bweze services list bweze services set --pre-deploy-command "npm run migrate" bweze services set --schedule "0 2 * * *" --time-limit 30m # a cron job # Runs on the live release and prints its output; the CLI exits with the command's code. bweze jobs run -- npm run backfill --since 2026-11-01 bweze jobs list bweze jobs logs --follow bweze jobs cancel ``` The same through the API: `GET /v1/projects/{id}/services`, `GET` and `PATCH /v1/services/{id}`, and `/v1/services/{id}/jobs` (spec: `https://api.bweze.com/v1/openapi.json`). Changing settings needs `deployment:update`; running or stopping a job needs `terminal:exec`, since it runs a command with the service's secrets. ## Environment variables [#environment-variables] Apps usually need config - a database URL, an API key. On the Deploy form, add them under **Environment variables**, one `KEY=VALUE` per line: ```bash DATABASE_URL=postgres://… API_KEY=… ``` They're available at both build and runtime. To change them later, update and **Redeploy**. ## Deploy a private repo [#deploy-a-private-repo] Private repos deploy through BWEZE's GitHub app - a one-time connection per workspace. 1. Open **Settings → Connect GitHub** and install the BWEZE app on your account or org. Grant it the repositories you want to deploy. 2. Back on **Deploy**, switch to **Private repo** and pick a repo from the dropdown. 3. Click **Deploy**. BWEZE only ever uses a short-lived, single-repo token to clone your code - it never stores your GitHub password, and one workspace can never see another's repositories or deployments. ## Redeploy, logs, and teardown [#redeploy-logs-and-teardown] Each app in the Deploy list has: * **Redeploy** - rebuild and ship the latest commit. * **logs** - the build output, live while a build runs (so a failed build tells you why). * **Remove** - tear the app down completely. ## Auto-deploy on push [#auto-deploy-on-push] Once a private repo is connected, every push to its deployed branch automatically rebuilds and ships the app - no manual redeploy needed. # Domains (/docs/domains) Every BWEZE project can have custom domains. You can **buy** a domain through BWEZE, **connect** a domain you already own, or claim a free `*.bweze.app` subdomain that goes live instantly. Domains belong to a project - pass the project id in the paths below. ## Search availability + price - `GET /v1/domains/search` [#search-availability--price---get-v1domainssearch] Pass a bare name (checked across `.com`, `.app`, `.dev`, `.io`, `.co`, `.xyz`, `.rw`) or a full domain: ```bash curl "https://api.bweze.com/v1/domains/search?q=mycompany" \ -H "authorization: Bearer bw_sk_..." ``` ```json { "results": [ { "domain": "mycompany.com", "available": true, "priceMinor": 18000, "currency": "RWF" } ] } ``` `priceMinor` is the price of the first year in RWF. It is `null` when BWEZE does not sell that domain: BWEZE sells one name under a suffix below (`mycompany.com`, `mycompany.co.rw`), not subdomains. ## Prices [#prices] RWF for one year, taken from your workspace's wallet when you buy: | Suffix | Price | Suffix | Price | | ------ | ------- | --------- | ------ | | `.com` | 18,000 | `.xyz` | 4,500 | | `.net` | 21,000 | `.site` | 7,500 | | `.org` | 18,000 | `.online` | 7,500 | | `.app` | 21,000 | `.store` | 9,000 | | `.dev` | 21,000 | `.tech` | 9,000 | | `.io` | 58,500 | `.cloud` | 18,000 | | `.co` | 42,000 | `.rw` | 30,000 | | `.ai` | 105,000 | `.co.rw` | 18,000 | | | | `.org.rw` | 18,000 | These are part of the published price list, `GET /v1/pricing`, which is the authority: a price only goes up with 30 days' notice. ## Buy a domain - `POST /v1/projects/{id}/register-domain` [#buy-a-domain---post-v1projectsidregister-domain] Registers a domain and attaches it to the project. Search first to see the price. **It spends money.** The price leaves your workspace's wallet when you buy, as a `domain_charge` in your transactions: * The registration is `registered` when the registrar accepts it at once. * It is `requested` while BWEZE registers it by hand (for most suffixes no registrar is connected yet). It is already paid for. * It is `failed` when the domain cannot be registered. The full price goes back to your wallet (a `domain_refund`, and `refund_transaction_id` is set). A purchase is refused, and nothing is charged, when: * your available balance cannot cover the price: `402 insufficient_balance`, with `priceMinor` and `availableMinor`. Your available balance is the wallet minus usage not yet settled and SMS sends in progress. Top up first; retrying without a top-up keeps failing; * the domain is already registered (`409 domain_taken`), or already being bought through BWEZE (`409 domain_unavailable`), so a retried request never pays twice; * BWEZE does not sell it (`400 domain_not_sold`). The domain is registered in **your** name: `registrant` is its owner on record (the registrant and admin contact at the registry), not BWEZE. The registry keeps these details and may show some of them in WHOIS lookups. ```bash curl -X POST https://api.bweze.com/v1/projects/PROJECT_ID/register-domain \ -H "authorization: Bearer bw_sk_..." -H "content-type: application/json" \ -d '{ "domain": "mycompany.rw", "registrant": { "name": "Aline Uwase", "organization": "My Company Ltd", "email": "aline@mycompany.rw", "phone": "+250.788123456", "street": ["KG 7 Ave"], "city": "Kigali", "countryCode": "RW" } }' ``` Required: `name`, `email`, `street` (one to three lines), `city` and `countryCode` (two letters). Optional: `organization`, `phone` (`+.`; Rwandan numbers like `0788123456` are converted), `state` and `postalCode`. The details are saved for the workspace, so a later purchase can leave `registrant` out and use them. With nothing saved, a purchase without it is refused with `registrant_required`. Sending changed details saves them as the new default; domains bought earlier keep the details they were bought with. CLI: ```bash bweze projects domains buy PROJECT_ID mycompany.rw \ --name "Aline Uwase" --email aline@mycompany.rw \ --street "KG 7 Ave" --city Kigali --country RW ``` The owner flags are `--name`, `--email`, `--street` (repeat for up to three lines), `--city` and `--country`, plus optional `--organization`, `--phone`, `--state` and `--postal-code`. Without them the CLI uses the workspace's saved owner; with none saved, it asks in a terminal and refuses under `--yes` or `--json`. It shows the price and the owner before it buys, and is charged the same way. ## Connect a domain you own - `POST /v1/projects/{id}/domains` [#connect-a-domain-you-own---post-v1projectsiddomains] Returns the two DNS records to add (a `TXT` ownership challenge and a `CNAME` to the BWEZE edge). A `*.bweze.app` subdomain skips DNS and activates instantly. ```bash curl -X POST https://api.bweze.com/v1/projects/PROJECT_ID/domains \ -H "authorization: Bearer bw_sk_..." -H "content-type: application/json" \ -d '{ "domain": "app.example.com" }' ``` After adding the records, verify: `POST /v1/domains/{id}/verify` (CLI: `bweze projects domains verify DOMAIN_ID`). Detach with `DELETE /v1/domains/{id}`. ## Check a .rw domain - `GET /v1/domains/rw/{name}` [#check-a-rw-domain---get-v1domainsrwname] ```bash curl https://api.bweze.com/v1/domains/rw/mycompany \ -H "authorization: Bearer bw_pk_..." ``` Publishable keys (`bw_pk_...`) are accepted - this endpoint is safe to call from clients. Returns: ```json { "domain": "mycompany.rw", "available": true } ``` `available` is `true`, `false`, or `null`. **`null` means the registry was unreachable - treat it as unknown, not as available.** # What is BWEZE? (/docs) BWEZE gives Rwandan developers one API and one CLI for the building blocks that are usually painful to wire up locally: push-to-deploy app hosting, hosted Postgres backends, SMS through the carriers, and `.rw` domains - all paid from one prepaid wallet. ## The pieces [#the-pieces] ## Principles [#principles] * **English-first, agent-readable.** Every error carries a machine-readable `code` and a `docs` URL. The whole platform is documented for LLM context windows at [/llms-full.txt](/llms-full.txt). * **Prepaid, never surprising.** Everything spends from a wallet you top up by mobile money. Zero balance blocks spending; it never goes negative. * **Idempotent by design.** Every mutating call takes an idempotency key. Retries never double-send or double-charge. # Messaging (/docs/messaging) ## Send - `POST /v1/messages` [#send---post-v1messages] Every request needs `Authorization: Bearer bw_sk_...` (secret key, server-side only). ```json { "to": "+250788123456", "template": "Your code is {{code}}", "data": { "code": 4821 }, "idempotencyKey": "signup-4821" } ``` Pass either `body` (literal text) or `template` + `data`. Returns: ```json { "id": "...", "status": "sent", "segments": 1, "encoding": "GSM7", "providerMessageId": "..." } ``` `status` moves `queued → sent → delivered | failed` as delivery receipts come back. ## Idempotency [#idempotency] Sends accept an idempotency key (`Idempotency-Key` header or `idempotencyKey` in the body). A retry with the same key returns the original result and never re-sends. Reusing a key with **different** content fails with `409 idempotency_key_reuse_mismatch`. Use a key on every mutating call. ## Segments and billing [#segments-and-billing] SMS is billed **per segment**, 15 RWF each: | Encoding | Single message | Multipart | | ---------------------- | -------------- | ----------------- | | GSM-7 (plain text) | 160 chars | 153 chars/segment | | UCS-2 (emoji, accents) | 70 chars | 67 chars/segment | A single message may be at most 10 segments (`400 message_too_long`). ## Preview - `POST /v1/messages/preview` [#preview---post-v1messagespreview] Same body, no send, no charge. Returns `{ encoding, segments, length }` - call it to show cost before sending. ## Opt-out [#opt-out] Recipients text **STOP** (or *hangana*, *guhagarara*) to opt out and **TUMA**/**START** to opt back in. Sends to opted-out numbers return `409 recipient_opted_out` - respect it, never loop. ## Failure modes [#failure-modes] * `402 insufficient_balance` - the wallet can't cover this send. Top up; do not retry blindly. * `409 recipient_opted_out` - do not retry. * Carrier failover is automatic: if a carrier bind is down, sends route through the surviving carrier. # Projects (/docs/projects) A **project** is the unit you deploy and manage on BWEZE. Every project has a type: * **`frontend`** - a web app / site deploy (push from git, live on `*.bweze.app` with SSL). * **`backend`** - a data stack: Postgres with auth, storage, realtime, and pgvector. You choose the type when you create the project. Domains, deployments, and other resources belong to a project. ## List projects - `GET /v1/projects` [#list-projects---get-v1projects] ```bash curl https://api.bweze.com/v1/projects \ -H "authorization: Bearer bw_sk_..." ``` ```json { "projects": [ { "id": "…", "name": "acme-web", "type": "frontend", "app": { "…": "…" }, "backend": null } ] } ``` ## Create a project - `POST /v1/projects` [#create-a-project---post-v1projects] ```bash curl -X POST https://api.bweze.com/v1/projects \ -H "authorization: Bearer bw_sk_..." -H "content-type: application/json" \ -d '{ "name": "acme-web", "type": "frontend" }' ``` `type` must be `"frontend"` or `"backend"`. ## Terminal - `POST /v1/projects/:id/exec` [#terminal---post-v1projectsidexec] Run a one-shot command inside the project's running container (the same shell the dashboard Terminal uses). Deploy the project at least once first - there must be a running container. ```bash curl -X POST https://api.bweze.com/v1/projects/{id}/exec \ -H "authorization: Bearer bw_sk_..." -H "content-type: application/json" \ -d '{ "command": "ls -la /app" }' ``` ```json { "output": "total 24\ndrwxr-xr-x ...", "truncated": false } ``` * **Body**: `{ "command": string }` (trimmed; max 8192 chars). * **Response**: `{ "output": string, "truncated": boolean }`. Output is capped at 256KB; if the command prints more, `output` ends with `... [output truncated]` and `truncated` is `true`. * **Auth**: **secret key only** (`bw_sk_...`) with the `terminal:exec` permission - available to `owner`, `admin`, and `developer` roles. Publishable keys (`bw_pk_...`) are rejected because exec is a write action. * **Timeout**: 30s. A longer-running command returns a `504` and is aborted. * **`409 no_container`**: the project has no running container yet - deploy it first. * **Kill switch**: set `BWEZE_PUBLIC_TERMINAL_EXEC=0` on the control plane to disable this endpoint platform-wide (returns `403 disabled`). ## CLI [#cli] ```bash bweze projects create acme-web --type frontend bweze projects domains connect acme-web app.example.com ``` ## From code [#from-code] The same calls with `fetch` (Node 18+, Deno, Bun, or any runtime with `fetch`): ```ts const api = (path: string, init: RequestInit = {}) => fetch(`https://api.bweze.com${path}`, { ...init, headers: { authorization: `Bearer ${process.env.BWEZE_API_KEY}`, "content-type": "application/json", ...init.headers, }, }).then((r) => r.json()); await api("/v1/projects", { method: "POST", body: JSON.stringify({ name: "acme-web", type: "frontend" }), }); const { projects } = await api("/v1/projects"); // Run a command in the project's container: const { output, truncated } = await api("/v1/projects//exec", { method: "POST", body: JSON.stringify({ command: "ls -la /app" }), }); ``` # Quickstart (/docs/quickstart) Ship phone verification for Rwandan mobiles with one dependency and no build step, using the OTP template. ## 1. Get a key and balance [#1-get-a-key-and-balance] In the dashboard: create a workspace, create an [API token](/docs/api-tokens) from the **Send SMS** template (`bw_sk_...`, shown once), and top up the wallet under **Billing**. Sends are prepaid - 15 RWF per SMS segment. A zero-balance workspace gets `402 insufficient_balance` on its first send. ## 2. Run the template [#2-run-the-template] ```bash cp .env.example .env # put your bw_sk_... key in npm install # pulls @bweze/messaging from npm node --env-file=.env server.mjs ``` ## 3. Send and verify [#3-send-and-verify] ```bash curl -X POST localhost:8787/otp/send -H content-type:application/json \ -d '{"phone":"0788123456"}' # → SMS: "Your MyApp code is 481953. It expires in 5 minutes." curl -X POST localhost:8787/otp/verify -H content-type:application/json \ -d '{"phone":"0788123456","code":"481953"}' # → {"ok":true} ``` Codes are hashed at rest, single-use, expire in 5 minutes, burn after 5 wrong attempts, and resends are cooled down 60 seconds. `node --test test.mjs` asserts all of it - including a live send when `BWEZE_API_KEY` is set. ## Or call the API directly [#or-call-the-api-directly] ```ts import { BwezeMessaging } from "@bweze/messaging"; const sms = new BwezeMessaging({ apiKey: process.env.BWEZE_API_KEY! }); await sms.send({ to: "+250788123456", template: "Your code is {{code}}", data: { code: 4821 }, idempotencyKey: "signup-4821", }); ``` # BWEZE as a registrar (EPP) (/docs/registrar) Most platforms resell domains through a third-party registrar's HTTP API. BWEZE goes one level deeper for `.rw`: it speaks **EPP** - the Extensible Provisioning Protocol - directly to the registry. That means a `.rw` domain you buy through BWEZE is created at the registry by BWEZE acting as an accredited registrar, not proxied through a reseller. ## What EPP is [#what-epp-is] EPP is the standard registry protocol (RFC 5730, with object mappings for \[domains 5731], \[contacts 5733], and \[hosts/nameservers 5732]) carried over a TLS-secured TCP transport (RFC 5734). A registrar opens a session, logs in with its credentials, and exchanges XML commands - `check`, `info`, `create`, `update`, `renew`, `transfer`, `delete` - against the registry's objects. Each message is length-prefixed on the wire; every command gets a result code, where anything `>= 2000` is an error. BWEZE ships its own EPP client, so there's no third-party dependency between the control plane and the registry. ## Which registries [#which-registries] | Registry | TLDs | Transport | Status | | -------- | ----------------------------- | ------------ | -------------------- | | RICTA | `.rw`, `.co.rw`, `.org.rw`, … | EPP over TLS | **first target** | | others | `.com`, `.app`, `.io`, … | reseller API | via provider adapter | Non-`.rw` TLDs still register through a provider adapter - EPP is the direct path we use where BWEZE is (or is becoming) the accredited registrar. ## The domain lifecycle [#the-domain-lifecycle] You never write EPP XML yourself. You use the same domains API/CLI/platform as any other domain (see [Domains](/docs/domains)); BWEZE translates to EPP under the hood for `.rw`. * **check** - availability. `GET /v1/domains/search` (or the `.rw`-specific `GET /v1/domains/rw/{name}`) maps to EPP `domain:check` when the registry is configured, falling back to RDAP otherwise. * **create** - `POST /v1/projects/{id}/register-domain` maps to EPP `domain:create`. BWEZE first ensures the **contacts** exist - the buyer as registrant and admin contact, BWEZE as tech contact (it runs the nameservers) - and the BWEZE **nameserver** host objects, then creates the domain in the buyer's name, delegated to those nameservers. Each set of owner details gets its own registry contact. * **renew** - `domain:renew` from the current expiry. * **transfer** - `domain:transfer` (request / query / approve / reject / cancel) using the domain's authInfo. * **delete** - `domain:delete`. Every `.rw` domain BWEZE registers is delegated to BWEZE's own authoritative nameservers: ``` ns1.bweze.com ns2.bweze.com ``` Because BWEZE controls that DNS (PowerDNS), a domain you buy is connected to your project and routed automatically - no manual DNS step. ## Going live - operational prerequisites [#going-live---operational-prerequisites] The EPP path is **config-gated and off by default**. BWEZE is not yet an accredited `.rw` registrar; enabling real registration requires: 1. **RICTA registrar accreditation.** BWEZE must complete RICTA's registrar accreditation (the RICTA registrar opportunity) to receive production EPP credentials. 2. **OT\&E credentials first.** Registries issue Operational Test & Evaluation (OT\&E / sandbox) credentials to validate the integration before touching production. Point `EPP_RW_HOST` at the OT\&E endpoint until certified. 3. **Public nameservers.** `ns1.bweze.com` / `ns2.bweze.com` must resolve to stable public IPs running PowerDNS. For `.rw` they are hosts outside the registry's own zone, so no glue is needed there: ordinary A records in `bweze.com` are enough. Glue matters for `.com`/`.net` domains, and `bweze.com`'s registrar cannot add it today (`infra/NAMESERVERS.md`). 4. **Credentials in the control plane.** Set `EPP_RW_HOST`, `EPP_RW_CLID`, `EPP_RW_PW`, and the mutual-TLS material (`EPP_RW_CLIENT_CERT`, `EPP_RW_CLIENT_KEY`, `EPP_RW_CA`) in the `apps/web` environment. `EPP_RW_TECH_CONTACT_ID` names BWEZE's own contact (default `BWEZE`). Until all of that is in place, `.rw` availability answers over RDAP and a purchase records a `requested` registration that BWEZE fulfils manually - the API surface is identical either way. The buyer pays up front in both cases; a registration the registry refuses, or that BWEZE cannot complete by hand, is refunded in full.