Getting started

# Clients & SDKs

Talk to the Zazu API from the terminal, a script, or your app. Every endpoint in these docs shows a request in all ten clients below — this page is how you install and authenticate each one.

## The official clients

Zazu ships nine maintained clients plus plain `curl`. They all read the same `ZAZU_API_KEY` / `ZAZU_BASE_URL` environment variables and target the same REST API, so pick whichever fits your stack. Each is open source on GitHub:

- CLI — [GitHubgetzazu/cli](https://github.com/getzazu/cli)
- JavaScript / TypeScript — [GitHubgetzazu/zazu-ts](https://github.com/getzazu/zazu-ts)
- Ruby — [GitHubgetzazu/zazu-ruby](https://github.com/getzazu/zazu-ruby)
- Python — [GitHubgetzazu/zazu-python](https://github.com/getzazu/zazu-python)
- Go — [GitHubgetzazu/zazu-go](https://github.com/getzazu/zazu-go)
- Rust — [GitHubgetzazu/zazu-rust](https://github.com/getzazu/zazu-rust)
- Elixir — [GitHubgetzazu/zazu-elixir](https://github.com/getzazu/zazu-elixir)
- Crystal — [GitHubgetzazu/zazu-crystal](https://github.com/getzazu/zazu-crystal)
- PHP — [GitHubgetzazu/zazu-php](https://github.com/getzazu/zazu-php)

## Authentication

Every client authenticates with an API key you generate from **Settings → Developer → API Keys**. Keep it in the `ZAZU_API_KEY` environment variable rather than hardcoding it — all eight SDKs and the CLI read it automatically:

```shell
export ZAZU_API_KEY="sk_live_..."
```

> **Sandbox first:** Start with a staging key against the sandbox base URL, then mint a production key and switch `ZAZU_BASE_URL` when you go live. See the Sandbox & test cards guide.

## curl

No install — every request is a signed HTTP call. Pass your key as a `Bearer` token:

```shell
curl "https://zazu.africa/api/entity" \
  -H "Authorization: Bearer $ZAZU_API_KEY"
```

## CLI

[GitHubView on GitHub](https://github.com/getzazu/cli)

A single self-contained binary (the Bun runtime is bundled — no Node, Bun, or Ruby needed). Install via Homebrew or npm:

```shell
# Homebrew (macOS / Linux)
brew install getzazu/tap/zazu

# or npm (thin shim that fetches the platform binary)
npm install -g @getzazu/cli
```

Authenticate once, then call any endpoint:

```shell
# interactive login, or pipe a key in for CI:
printf '%s\n' "$ZAZU_API_KEY" | zazu login --api-key-stdin

zazu accounts list
```

## JavaScript / TypeScript

[GitHubView on GitHub](https://github.com/getzazu/zazu-ts)

Runtime-agnostic (Node 20+, Bun, Deno, browsers, Workers). Install `@getzazu/sdk` with your package manager:

```shell
bun add @getzazu/sdk    # or npm / pnpm / yarn
```

```javascript
import { Zazu } from "@getzazu/sdk";

// On Node/Bun the key is read from ZAZU_API_KEY automatically.
const zazu = new Zazu({ apiKey: process.env.ZAZU_API_KEY });

const accounts = await zazu.accounts.list();
```

## Ruby

[GitHubView on GitHub](https://github.com/getzazu/zazu-ruby)

Published as `zazu-ruby` on RubyGems but required as `zazu` in code. Add it to your Gemfile:

```ruby
gem "zazu-ruby"
```

```ruby
require "zazu"

zazu = Zazu.new(api_key: ENV["ZAZU_API_KEY"])

accounts = zazu.accounts.list
```

## Python

[GitHubView on GitHub](https://github.com/getzazu/zazu-python)

Requires Python 3.11+. Install `zazu-sdk` from PyPI:

```shell
pip install zazu-sdk
```

```python
from zazu_sdk import Zazu

# Picks up ZAZU_API_KEY from the environment by default.
client = Zazu(api_key="sk_live_...")

accounts = client.accounts.list()
```

## Go

[GitHubView on GitHub](https://github.com/getzazu/zazu-go)

Requires Go 1.24+; no runtime dependencies outside the standard library. Install with `go get`:

```shell
go get github.com/getzazu/zazu-go
```

```go
import zazu "github.com/getzazu/zazu-go"

// Reads ZAZU_API_KEY from the environment by default.
client, err := zazu.New()

accounts, err := client.Accounts.List(ctx, zazu.AccountListParams{})
```

## Rust

[GitHubView on GitHub](https://github.com/getzazu/zazu-rust)

Install `zazu-sdk` as a git dependency for now (not yet on crates.io):

```toml
zazu-sdk = { git = "https://github.com/getzazu/zazu-rust" }
```

```rust
// Falls back to the ZAZU_API_KEY env var when api_key isn't set.
let client = zazu_sdk::Client::builder()
    .api_key(std::env::var("ZAZU_API_KEY")?)
    .build()?;

let accounts = client.accounts().list(Default::default())?;
```

## Elixir

[GitHubView on GitHub](https://github.com/getzazu/zazu-elixir)

Install `:zazu` as a GitHub dependency in your `mix.exs`:

```elixir
{:zazu, github: "getzazu/zazu-elixir"}
```

```elixir
# :api_key defaults to the ZAZU_API_KEY env var.
{:ok, client} = Zazu.new(api_key: System.fetch_env!("ZAZU_API_KEY"))

{:ok, accounts} = Zazu.Accounts.list(client)
```

## Crystal

[GitHubView on GitHub](https://github.com/getzazu/zazu-crystal)

Install `zazu` as a GitHub dependency in your `shard.yml`:

```yaml
dependencies:
  zazu:
    github: getzazu/zazu-crystal
```

```crystal
require "zazu"

client = Zazu::Client.new # reads ZAZU_API_KEY

accounts = client.accounts.list
```

## PHP

[GitHubView on GitHub](https://github.com/getzazu/zazu-php)

Requires PHP 8.2+. Install `getzazu/zazu-php` with Composer:

```shell
composer require getzazu/zazu-php
```

```php
use Zazu\Client;

// apiKey defaults to the ZAZU_API_KEY env var.
$client = new Client(apiKey: getenv('ZAZU_API_KEY'));

$accounts = $client->accounts->list();
```