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

✓ Checkpoint: the CLI prints the key's `id` (starting with `key_`), its `prefix` and `mode` `test`, and `key.txt` holds a key that starts with `sk_rtest_`.

## 2. Make your first request

Send the key in the `Authorization: Bearer` header. The `limit` parameter accepts 1 to 100.

```bash
curl -sS "$BUSINESS_API/customers?limit=5" \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch("$BUSINESS_API/customers?limit=5", {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const page = await res.json();
```

```python
import os, requests

res = requests.get(
    "$BUSINESS_API/customers?limit=5",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
page = res.json()
```

```go
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:

```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"
}
```

✓ Checkpoint: the status is `200`, `data` lists customers whose `id` starts with `cus_`, and `has_more` tells you whether another page exists; if it does, request it with `after` set to `next_cursor`.

## 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
```

✓ Checkpoint: the `webhooks listen` terminal prints a line such as `2026-11-19T10:42:05Z  --> invoice.paid [wev_2pQ9fLhS3jD6qA1zC8vN5mK7eRt]  <-- 200 OK (12ms)`, showing the status your server returned.

## 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

- [Verify the signature on every webhook](/docs/webhooks/verify)
- [Choose the scopes for a restricted key](/docs/getting-started/restricted-keys)
- [What the sandbox contains and how to simulate payments](/docs/getting-started/sandbox)
- [Import your customers through the API](/docs/guides/import-customers)

