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 gotactl CLI installed, plus curl, Node.js, Python or Go on your machine.
  • The developer:write permission in the sandbox, to create the key. The key itself needs only business:customers:read, the permission behind the listCustomers operation.
  • A local server answering 200 at http://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.

bash
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"

The response, trimmed to one customer:

json
{
  "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.

bash
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.

bash
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.

Next steps#