Quickstart
Enter the sandbox, create a restricted test key, list the sample customers and receive your first signed event on a local server.
What you will build#
A minimal integration running in your utility's sandbox: a test key that holds one permission, a request that returns the sample customers, and a local server that receives signed events through the gotactl CLI. The sandbox is a separate test workspace, so none of these steps touch the company's real data.
Prerequisites#
- An account with a sandbox. When the plan includes test environments, sign-up creates a sandbox filled with sample data and makes you its owner. In the dashboard, enter it from the account menu with Switch to sandbox.
- The
gotactlCLI installed, pluscurl, Node.js, Python or Go on your machine. - The
developer:writepermission in the sandbox, to create the key. The key itself needs onlybusiness:customers:read, the permission behind thelistCustomersoperation. - A local server answering
200athttp://localhost:3000/hook, for step 3.
1. Create a restricted test key#
Sign in to the CLI straight into the sandbox context (its ID is listed by gotactl contexts list) and create the key. Passing a scope makes the key restricted; inside a sandbox the mode is always test.
gotactl auth login --context mbr_2pQ6vRb2HkT9wF4nJ7cX1sL3yGm
gotactl api-keys create --name quickstart --mode test \
--scope business:customers:read --out key.txt
export API_KEY="$(cat key.txt)"
Prefer the dashboard? Open Developers, then the API keys tab, click New key, fill in Name, pick Restricted: your choice under Type and Test under Mode, tick business:customers:read and click Create key. The full key is shown once, right after it is created.
2. Make your first request#
Send the key in the Authorization: Bearer header. The limit parameter accepts 1 to 100.
curl -sS "$BUSINESS_API/customers?limit=5" \
-H "Authorization: Bearer $API_KEY"
const res = await fetch("$BUSINESS_API/customers?limit=5", {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const page = await res.json();
import os, requests
res = requests.get(
"$BUSINESS_API/customers?limit=5",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
page = res.json()
req, _ := http.NewRequest("GET", "$BUSINESS_API/customers?limit=5", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("API_KEY"))
resp, err := http.DefaultClient.Do(req)
The response, trimmed to one customer:
{
"data": [
{
"id": "cus_2pQ7xKfR9mW3nT8vB4yL6cJ1dHs",
"tenant_id": "ten_2pQ8aNcV5tY2kM7wE3rU9gZ4bXf",
"customer_type": "individual",
"category": "residential",
"display_name": "Ana Macuácua",
"phone": "+258841234567",
"status": "active",
"created_at": "2026-11-02T09:14:07Z",
"updated_at": "2026-11-02T09:14:07Z"
}
],
"has_more": true,
"next_cursor": "Y3VzXzJwUTlmTGhTM2pENnFBMXpDOHZONW1LN2VSdHwxNzkzNjExOTA0NTEyMDAwMDAw"
}
3. Receive your first event locally#
The CLI reads the sandbox's events and forwards each one to your server, signed with the webhook-id, webhook-timestamp and webhook-signature headers. It prints the signing secret, which starts with whsec_, when it starts.
gotactl webhooks listen --forward-to http://localhost:3000/hook
In a second terminal, cause a real event: the CLI creates and issues a test invoice, then records a payment for the same amount, which leaves the invoice paid.
gotactl events trigger invoice.paid
Test it#
In the dashboard, open Developers and the Events tab: invoice.paid is in the list, and its detail holds the full payload. The request from step 2 appears under Logs, labelled with the key's prefix. From the terminal, gotactl customers list --limit 5 returns the same page.