Developers

Getting started

The API lives at https://ubunya.com/api/v1. Make an API key under Manage → Integrations in your community, then:

curl https://ubunya.com/api/v1/organization \
  -H "Authorization: Bearer ubk_…"

You get back your community and the person the key acts as. The same calls power the MCP server and the CLI, so whatever works here works there.

Authentication

API keys (start with ubk_) are for your own scripts and servers. A key is read only or read and write, and it can never do more than the person who made it: if their role changes, so does the key. Revoke a key at any time on the Integrations page.

OAuth 2.1 is for apps other people use. Discovery is at https://ubunya.com/.well-known/oauth-authorization-server. We support the authorization code flow with PKCE (S256, required), refresh tokens that rotate on every use, and dynamic client registration at /api/oauth/register. Scopes are read and write. On the consent screen the person picks one of the communities where they're staff. Access tokens last an hour; refresh tokens 30 days.

# 1. Send people to
https://ubunya.com/api/oauth/authorize?response_type=code&client_id=…&redirect_uri=…
  &code_challenge=…&code_challenge_method=S256&scope=read%20write&state=…

# 2. Swap the code they come back with
curl -X POST https://ubunya.com/api/oauth/token \
  -d grant_type=authorization_code -d client_id=… -d code=… \
  -d redirect_uri=… -d code_verifier=…

Pages, errors and limits

Lists return {"data": […], "next": 123}. Pass next back as after for the following page; it's null on the last one. limit goes up to 200. Dates are ISO 8601, amounts are strings in your community's currency.

Errors come as {"detail": "…"} with a plain sentence you can show people: 400 when a rule stops the action (an intake is full, a payment is more than the balance), 401 for a missing or revoked credential, 403 when the scope or the person's role doesn't allow it, 404 when it isn't in your community, and 429 above 600 requests a minute.

Webhooks

Add a URL under Manage → Integrations and we POST each event to it as JSON as it happens, retrying for about a day if your end is down. Every request carries Ubunya-Event, Ubunya-Delivery (unique, so you can ignore repeats) and Ubunya-Signature.

Check the signature before trusting a request: HMAC-SHA256 of <t>.<raw body> with your signing secret must equal v1 in Ubunya-Signature: t=…,v1=…. Reject old t values to stop replays.

# Python
import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes, tolerance=300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    signed = f"{parts['t']}.".encode() + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts["t"])) < tolerance
    return fresh and hmac.compare_digest(expected, parts["v1"])

// Node.js
import crypto from "node:crypto";

export function verify(secret, header, rawBody, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < tolerance;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Zapier and Make

The quickest way: in Zapier or Make, add a Catch hook step, copy its URL, and add it as a webhook in Ubunya with the events you want. For a full integration, use REST hooks with an API key or OAuth: POST /hooks with {"target_url", "event"} to subscribe, DELETE /hooks/{id} to unsubscribe, and GET /hooks/samples/{event} for sample data while someone builds their Zap.

MCP server (Claude and other AI apps)

Let an assistant answer questions like “who still owes for Cohort 5?” or “accept the waitlisted applicants”. Add a custom connector with this URL; the app signs you in with Ubunya and asks which community to use:

https://ubunya.com/api/mcp

In Claude: Settings → Connectors → Add custom connector. Tools that change something are marked, so the assistant asks before using them. Clients that can't do OAuth can send an API key as Authorization: Bearer ubk_….

Command line

pipx install ubunya        # or: uv tool install ubunya
ubunya login               # opens your browser; pick the community
ubunya members
ubunya applications --status submitted
ubunya decide 42 accept --message "Welcome!"
ubunya balances --owing
ubunya pay 812 2500 --method mpesa --ref SGT7H2XYZ
ubunya api GET /sessions   # any endpoint, JSON out

Add --json to any command. Use ubunya login --key ubk_… on servers without a browser.