One API for everything you see in the dashboard.
API keys in any context, signed webhooks and a CLI.
API
Integrate your systems with a clean API. The REST API is described by an OpenAPI document, and the reference in the dashboard lists each operation's parameters and responses. Keys are created under Developers, API keys: a secret key carries the permissions of the person who made it, a restricted key carries only the scopes you select, and the prefix shows whether it is a test or live key. The usual path starts in the sandbox with a test key, which a live tenant refuses, and moves to a live key with no code changes.
- Keys with limitsSet scopes, an expiry date and a list of IPs or CIDR ranges the key may be used from.
- Rolling without downtimeWhen you roll a key, the old one keeps working for an overlap you choose, up to seven days.
- Idempotency-KeyRepeating a POST with the same key within 24 hours returns the stored response, while a different body under that key gets a 409.
- Request-Id and problem+jsonEvery response carries a Request-Id, and errors arrive as problem+json with a documented error_code.
- Per-key rate limitsRateLimit-Limit, RateLimit-Remaining and RateLimit-Reset report the remaining budget, and a spent budget answers 429 with Retry-After.
- Request logFilter calls in the dashboard by method, path, key or Request-Id, with sensitive fields stripped before anything is stored.
Docs: API
Webhooks
React to every event in real time. Register an HTTPS URL, pick event types across invoices, payments, readings, meters, connections, work orders, collections and more, or subscribe to all of them, then store the whsec_ signing secret, which is shown only once. Deliveries follow Standard Webhooks, with webhook-id, webhook-timestamp and an HMAC-SHA256 webhook-signature header, so stock verification libraries work. Private and internal addresses are refused when the URL is saved and checked again at connect time.
- Retries with growing delaysA non-2xx answer or a connection failure schedules another attempt, spaced further apart each time, for up to 72 hours.
- Endpoint healthAn endpoint that fails for 72 hours, or answers 410 Gone, is paused, and its deliveries are held until you resume it.
- Secret rotation with overlapDuring the rotation window each delivery carries two signatures, one per secret, so you can switch secrets without dropping any.
- Bulk redeliveryRequeue the failed deliveries from a window of up to seven days, sent in order per record, after a dry-run count.
- Per-delivery historyInspect the payload, HTTP status, response body and next attempt time, and resend any single delivery.
- Test eventSend a webhook.test event from the dashboard to check that your receiver verifies signatures.
Docs: Webhooks
CLI
Automate operations and tests from your shell. The CLI signs in with a device grant that prints a code and a terminal QR, so it works over SSH and inside containers with no browser; it also supports browser sign-in with PKCE, or an API key read from the environment or stdin and never from a flag. It lists and fetches customers, accounts, invoices, payments and readings, submits readings, manages API keys and switches contexts. In a sandbox it triggers real events and forwards them to a local server.
- JSON output for scriptsThe --json flag prints JSON to stdout, optionally limited to chosen fields, and exit codes tell apart missing sign-in, not found and rate limiting.
- Webhooks on localhostwebhooks listen forwards sandbox events to a local URL, signed with a temporary secret, and refuses a live context unless you confirm it twice.
- Event triggersevents trigger creates a sample customer, account, issued or paid invoice, payment or reading in the sandbox, along with its event.
- Advance the sandboxsandbox advance confirms, fails or expires pending simulated payments and can generate a fresh cycle of meter readings.
- Raw API callsThe api command sends a request to any path found through the API catalog, with fields, headers and cursor pagination.
- Credentials kept safeSecrets live in the OS keychain or a 0600 file, and a config file readable by others is refused.
Docs: CLI
The CLI
Sign in with a code in the dashboard, without pasting keys into the terminal, and use the same APIs from the command line.
$ gotactl auth login Open the dashboard and confirm the code ✓ Signed in
# The API address comes from the catalog: # https://api.gota.umbeluzi.com/.well-known/api-catalog $ curl -H "Authorization: Bearer sk_test_••••1a2b" \ "https://api.gota.umbeluzi.com/…/customers"