The Barazas API

Getting a key

Keys are generated in your portal by a client admin. Each one is scoped: you choose what it may read when you create it, and that cannot be widened afterwards without creating a new one.

1. Sign in to your portal and open API keys.
2. Name the key after what it is for, and tick only the scopes that thing needs.
3. Copy the key and the secret.

The secret is shown once, at the moment the key is created. It cannot be recovered afterwards, only replaced. Store it where your application reads its configuration from, not in a message to yourself.

Every key expires, and none may last longer than a year (365 days). Plan for rotation: create the replacement, move your application onto it, then revoke the old one. A key that has expired answers with 401 exactly as a revoked one does.

Authentication

HTTP Basic. The key is the username, the secret is the password.

curl https://barazas.com/api/v1/client/events \
  -u "bzk_live_xxxxxxxx:YOUR_SECRET"

Some hosts strip the Authorization header before it reaches the application. If yours does, send the same two values as headers instead:

curl https://barazas.com/api/v1/client/events \
  -H "X-Api-Key: bzk_live_xxxxxxxx" \
  -H "X-Api-Secret: YOUR_SECRET"

Send requests from your server, never from a browser. A key in front-end JavaScript is a key published to everyone who opens the page.

Postman collection

Every endpoint below, as a collection you can import into Postman and send in a minute. It is generated from this API itself each time it is downloaded, so it cannot describe an endpoint that no longer exists or name a scope that has changed.

Download the collection

1. In Postman, choose Import and select the downloaded file.
2. Open the collection’s Variables tab and fill in apiKey and apiSecret.
3. Set eventSlug to one of your events, then send Events to check the key works.

The collection ships with the credential fields empty, and that is how it should leave your machine. Fill them in your own Postman environment rather than in the collection, and do not commit a filled-in collection or share it into a workspace: a secret in a collection file is a secret in every copy of it.

Scopes

A key may only read what it was granted. Asking for anything else returns 403 and names the scope that was missing.

attendees:pii returns email addresses, phone numbers and identity document numbers. Grant it only to a key used by a system that needs them, and never to one whose credentials sit in a website template.

Endpoints

All paths are relative to https://barazas.com/api/v1. Everything is read-only, and only events in your organisation’s current active period are reachable.

An example response

{
  "data": [
    {
      "id": 41,
      "title": "Official Opening Ceremony",
      "type": "ceremony",
      "track": null,
      "starts_at": "2026-10-22T08:30:00+03:00",
      "ends_at": "2026-10-22T10:00:00+03:00",
      "day": "2026-10-22",
      "speakers": [
        { "id": 9, "name": "Dr Amara Kone", "organization": "National Research Agency" }
      ]
    }
  ],
  "meta": { "days": ["2026-10-22", "2026-10-23"], "timezone": "Africa/Nairobi" }
}

Pagination

Only the delegate list paginates. Pass page and per_page; per_page defaults to 50 and is capped at 200.

"meta": {
  "current_page": 1,
  "last_page": 7,
  "per_page": 50,
  "total": 312,
  "personal_data_included": false
}

personal_data_included says whether the response carried personal fields. It is there so an empty email is distinguishable from a withheld one.

Errors

A 403 names what was missing and what the key does hold, so the fix does not require a support conversation:

{
  "message": "This key does not have the attendees:read scope.",
  "required_scope": "attendees:read",
  "granted_scopes": ["programme:read", "speakers:read"]
}

Rate limits

120 requests a minute per key. If you are drawing a programme onto a public page, cache the response rather than calling on every page view: the programme changes a few times a week, not a few times a second.

What the API does not do

Stated plainly, so you do not spend an afternoon looking for it:

• Nothing writes. There is no way to create or change an event, a session or a delegate. A key that could change an event is a key that could cancel one.
• Past periods are unreachable. A key only ever sees the active one.
• Nothing about payments, invoices or your subscription is exposed.

If you need something that is not here, tell us what you are building.