---
title: "Authentication"
description: "API keys, their secrets and permissions."
url: "https://docs.goomzo.africa/docs/developers/authentication"
docs_index: /llms.txt
lastUpdated: 2026-11-13
section: "Overview"
related:
  - /docs/developers
  - /docs/developers/idempotency
  - /docs/developers/rate-limits
  - /docs/developers/errors
---

> For an index of all documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt). Any page is also available as Markdown by adding .md to its URL.

# Authentication

> API keys, their secrets and permissions.

Every API request is made with an API key: a sign-in for one of your systems, such as your shop, not for a
person. You give each key only the permissions it needs.

An API key has an ID, which starts with `sva_`, and one or more secrets, which start with `gzk_`. The secret is
what proves a request is yours.

## Create an API key

1. Open **Settings → API keys** and select **New API key**. Only the organization's owner and admins can.
2. Name it after the system that will use it, such as **Shop**.
3. Choose its permissions. Start from a bundle (Read only, Customer sync, Messaging or Full access) and adjust.
4. Choose when its first secret expires, and save. The secret is shown once, so copy it straight away.

<Callout>An API key's permissions can't be changed later. To change them, create a new key and switch over.</Callout>

You can have up to 50 API keys, and disable, enable or delete any of them.

## Permissions

| Permission                           | Lets it                                                                                      |
| ------------------------------------ | -------------------------------------------------------------------------------------------- |
| `customers.read`                     | List, search, open and export customers                                                      |
| `customers.write`                    | Add, import and edit customers, and set their segments                                       |
| `customers.delete`                   | Delete customers                                                                             |
| `activity.read`, `activity.write`    | Read and record customer activity                                                            |
| `segments.read`, `segments.write`    | List and manage segments and their members                                                   |
| `messages.read`, `messages.send`     | List and send messages                                                                       |
| `broadcasts.read`, `broadcasts.send` | List and send broadcasts                                                                     |
| `analytics.read`                     | Read analytics                                                                               |
| `payments.read`                      | Read your wallet, SMS balance and transactions                                               |
| `billing.read`                       | Read your plan, the plans for sale and plan invoices                                         |
| `webhooks.manage`                    | Add and manage [webhook](https://docs.goomzo.africa/docs/developers/webhooks?utm_source=llms&utm_medium=ai) endpoints, and see and resend deliveries |

## Secrets

A new API key comes with its first secret. To add another, open the key and select **Create secret**, name it
after where it's used, and choose when it expires: in 30 days, 90 days, a year, or never. An API key can have up
to 10 secrets, so you can add a new one, switch your system over, then revoke the old one.

Goomzo shows a secret only once, so copy it somewhere safe straight away.

Send it with every request as a Bearer token:

```http
Authorization: Bearer gzk_...
```

Or use Basic auth, with the key ID as the username and the secret as the password:

```bash
curl -u "sva_...:gzk_..." https://api.goomzo.africa/v1/customers
```

<Callout type="warn">
  Keep secrets out of your code and out of anything a customer's browser can see. If one leaks, select **Revoke** on it in the API key; it
  stops working right away.
</Callout>

## Key pairs

If you'd rather not store a long-lived secret, use a key pair instead. Your system signs a short JWT with its
private key and exchanges it for a token that lasts an hour.

1. In the API key, under **Advanced: key pairs**, select **Create key pair** to download a key file, or
   **Upload public key** to use your own Ed25519 key. Goomzo keeps only the public half.
2. Sign a JWT with the private key:

   ```text
   Header: { "alg": "EdDSA", "kid": "<key_id>" }
   Claims: { "iss": "sva_...", "aud": "https://api.goomzo.africa/v1/oauth/token",
             "jti": "<unique id>", "iat": <now>, "exp": <now + up to 300> }
   ```

   Each `jti` can be used only once. Add a `scope` claim, with permissions separated by spaces, to get a token
   with fewer permissions than the account.

   Use the `token_uri` from your key file as `aud`. Older key files name
   `https://app.goomzo.africa/v1/oauth/token`, which still works.

3. Exchange it for a token:

   ```bash
   curl https://api.goomzo.africa/v1/oauth/token \
     -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
     -d assertion=$SIGNED_JWT
   ```

   ```json
   { "access_token": "gzt_...", "token_type": "Bearer", "expires_in": 3600, "scope": "customers.read" }
   ```

4. Send `access_token` as a Bearer token until it expires, then sign a new JWT.

An API key can have up to 10 active key pairs.

---

For an index of all available documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt)