Keys and limits

Getting your key

• The organisation's owner (a school's director) signs in to Wellth and opens the portal's Connect screen. Nobody else can see it.
• Set your system's webhook address first. Payment numbers and bills refuse every call (409) until there is one, because Wellth must be able to tell your system about payments.
• Press Make the API key. The key is shown once. The first time, your webhook signing secret (whsec_ and 32 characters) is shown with it, also once.
• Put both in your system's secret store at once. Wellth keeps only a SHA-256 hash of the key and its last 4 characters, so it can never show the key again.

Sending it

Send the key in the Authorization header as a Bearer token, on every call. There are no sessions and no other headers to sign. Call Wellth from your server only: a key in a browser or a phone app is a leaked key.

curl https://wellth.example/api/org/v1/ping \
  -H "Authorization: Bearer $WELLTH_KEY"

{
  "ok": true,
  "school": "Demo Clinic Kisaasi",
  "handle": "democlinic",
  "mode": "test"
}

school is your organisation's name on Wellth and handle its @name (whatever kind of organisation you are: the field names come from the School API). mode is test or live, from the key you sent.

Test and live

• A Wellth running in development makes wsk_test_ keys; every deployed Wellth makes wsk_live_ keys. A key works only on the Wellth that made it.
• Ping answers "mode": "test" or "live" for the key you sent.
• Every webhook carries livemode: false while your organisation's newest key is a test key. In production, ignore events with livemode: false.

Rotating and stopping a key

• Make a new key on Connect: the new key works at once, and the one before keeps working 24 hours, then stops. Deploy the new key within that time.
• Stop this key now: the key stops at once. Use it when a key may have leaked, or when a rotated key shouldn't wait its 24 hours.
• Make a new signing secret: the old secret stops at once, with no overlap. Webhooks sent after that are signed with the new one, so update your receiver straight away.
• A stopped or expired key gets 401, like a wrong one.

Rate limit

At most 120 calls a minute per key, counted over the last 60 seconds (a placeholder: it may change before launch). Every call with a valid key counts, ping included. Call number 121 within the minute gets:

{ "error": "Too many calls: at most 120 a minute. Wait a minute and try again." }

There is no Retry-After header: wait, then try again. Sending a whole class's balances at the start of term? Spread the calls out, about two a second.

Gates: when a valid key is refused (403)

Each Wellth feature switches on in a country only once its licensed partner is in place. A key is checked against your organisation's gates on every call, after the rate limit. A closed gate answers 403 with its reason, in plain words you can show your staff.

The 403 messages, word for word (the gate's name and your country fill the gaps):

Connect a school system isn't switched on in Uganda yet.
Organisation payments isn't available in Kenya yet.
School fees is in a pilot with a few circles in Uganda. It opens to everyone once it's licensed.
Tall Grass checks every organisation before money moves. We'll be in touch.
Tall Grass hasn't recorded your data-processing agreement yet. Ask Tall Grass: the portal opens once it is signed.