Sign up

Authentication

Service accounts, access tokens and permissions.

Every API request is made by a service account: a sign-in for a system, not a person. You give it only the permissions it needs, and it proves who it is with an access token.

Create a service account

  1. Open Settings → Service accounts and select New service account. Only the organization's owner and admins can.
  2. Name it after the system that will use it, such as Shop.
  3. Turn on Test mode if it's for building and testing. Its messages reach no one and use no SMS. See Test mode.
  4. Choose its permissions. Start from a bundle (Read only, Customer sync, Messaging or Full access) and adjust.

A service account's permissions and test mode can't be changed later. To change them, create a new one and switch over.

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

Permissions

PermissionLets it
customers.readList, search, open and export customers
customers.writeAdd, import and edit customers, and set their segments
customers.deleteDelete customers
activity.read, activity.writeRead and record what customers did
segments.read, segments.writeList and manage segments and their members
messages.read, messages.sendList and send messages
broadcasts.read, broadcasts.sendList and send broadcasts
analytics.readRead analytics
billing.readRead your wallet, SMS balance and transactions
webhooks.manageAdd and manage webhook endpoints, and see and resend deliveries

Access tokens

Open the service account and select Create access token. Name it, and choose when it expires: in 30 days, 90 days, a year, or never. A service account can have up to 10.

The token starts with gzk_. Goomzo shows it only once, so copy it somewhere safe straight away.

Send it with every request as a Bearer token:

Authorization: Bearer gzk_...

Or use Basic auth, with the service account's ID as the username and the token as the password:

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

Keep tokens out of your code and out of anything a customer's browser can see. If one leaks, select Revoke on it in the service account; it stops working right away.

Key pairs

If you'd rather not keep a long-lived token, 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 service account, under Advanced: key pairs, select Create key 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:

    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:

    curl https://api.goomzo.africa/v1/oauth/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  -d assertion=$SIGNED_JWT
    { "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.

A service account can have up to 10 active keys.