Skip to main content

Getting started

This page takes you from nothing to a working call in four steps: get a key, request a token, check what the key can do, and list the company's programmes. Every step is read-only, so nothing in the company changes.

You need:

  • a Zooza company, and an account with the owner role in it;
  • a server-side environment with cURL, Node.js 18+ or Python 3 (the secret must never run in a browser).

1. Create a key​

A company owner creates keys in the Zooza app: Developers → API keys → New key. Other roles can't create keys.

A new key has:

PartExampleNotes
client_idzk_4768b32989b7303eac7ff30eNot secret. Identifies the key.
client_secret<client_secret>Shown once. Copy it straight into your secret store. If you lose it, rotate the key to get a new one.
Access groupscore_readWhat the key may call. New keys are read only.
Company scopepinnedThe key acts only for the company that created it.

Store the values as environment variables. Locally, use a .env file that is listed in .gitignore:

.env (git-ignored)
ZOOZA_CLIENT_ID=zk_…
ZOOZA_CLIENT_SECRET=<client_secret>
ZOOZA_OWNER_EMAIL=owner@yourcompany.example
ZOOZA_BASE_URL=https://api.zooza.app/v3

ZOOZA_OWNER_EMAIL is the email of an owner of the company: the token acts as that owner (see why). Use the base URL of your company's region.

Never paste the secret into chat

Don't paste client_secret into a chat, a support ticket or an AI agent. If an agent helps you write the code, let it read the secret from the environment.

2. Request an access token​

Exchange the key for a token at POST /v3/token.

curl -s -X POST "$ZOOZA_BASE_URL/token" \
-H "Content-Type: application/json" \
-d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$ZOOZA_CLIENT_ID\",\"client_secret\":\"$ZOOZA_CLIENT_SECRET\",\"email\":\"$ZOOZA_OWNER_EMAIL\"}"

The response:

{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 3600, "scope": "core_read" }

The token lasts 60 minutes. Cache it and reuse it for every call; don't request a new token per call, because the token operation has its own strict limit. If you get 401 invalid_client, see why a token request is refused.

3. Check the key: GET /v3/me​

GET /v3/me costs no points. It confirms the token works and shows what the key may do.

curl -s "$ZOOZA_BASE_URL/me" -H "Authorization: Bearer $ACCESS_TOKEN"
{
"client_id": "zk_…",
"region": "EU",
"groups": ["core_read"],
"tier": "free",
"points": { "limit_minute": 60, "remaining_minute": 60, "limit_day": 1000, "remaining_day": 1000,
"reset_day": "2026-11-19T00:00:00Z" },
"token": { "expires_at": "2026-11-18T11:00:00Z" },
"operations": [ { "op": "get_courses", "method": "GET", "path": "/v3/courses", "cost": 2 } ]
}

operations lists every operation the key may call, with its cost. Access and rate limits explains groups, tiers and points.

4. Make your first call: list programmes​

GET /v3/courses lists the company's programmes. It costs 2 points.

curl -s "$ZOOZA_BASE_URL/courses" -H "Authorization: Bearer $ACCESS_TOKEN"

Every response carries X-RateLimit-* headers with your remaining budget, in points.

Next steps​