Sign up

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.
An API key's permissions can't be changed later. To change them, create a new key and switch over.

You can have up to 50 API keys, 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 customer activity
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
payments.readRead your wallet, SMS balance and transactions
billing.readRead your plan, the plans for sale and plan invoices
webhooks.manageAdd and manage webhook 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:

Authorization: Bearer gzk_...

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

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

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.

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:

    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.

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

Last updated