Skip to main content

Authentication

This page covers authentication for the REST API only. Widgets do not require authentication — see the widget docs for embedding instructions.

Zooza uses passwordless login. Instead of relying on a password, identity is verified via email verification, PIN code, or client secret.

Required headers​

Every REST API request requires these three headers:

HeaderDescription
X-ZOOZA-API-KEYYour REST API key
X-ZOOZA-TOKENIdentifies the current user
X-ZOOZA-COMPANYScopes requests to a specific company

Obtaining your REST API key​

REST API keys are different from widget API keys and must be requested through Zooza support. A widget API key cannot be used for REST API calls.

Obtaining a user token​

There are three ways to obtain a token, depending on your use case.

Via email verification​

The most common approach for customer-facing applications.

  1. Send a POST request with the user's email.
  2. Zooza sends a verification email containing a link with a key query parameter.
  3. Extract the token from the URL and store it.

Example verification link:

https://yoursite.com?key=abc123token
curl -X POST https://api.zooza.app/v1/login \
  -H "Content-Type: application/json" \
  -H "X-ZOOZA-API-KEY: your_api_key" \
  -d '{
    "login": "customer@example.com",
    "verification_method": "email"
  }'

Store the token in a session, cookie, or localStorage, and include it in subsequent requests:

X-ZOOZA-TOKEN: <token>
note

This is a long-term token, but it may be invalidated by Zooza at any time.

Via PIN code​

Instead of clicking a verification link, users can enter a PIN code (valid for 5 minutes) from the same email.

curl -X POST https://api.zooza.app/v1/verify \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-ZOOZA-API-KEY: your_api_key" \
  -d '{
    "action": "validate_pin",
    "email": "customer@example.com",
    "pin": "123456"
  }'

Response:

{
  "message": "Code accepted",
  "token": "<token>"
}

Via client secret (server-to-server)​

For server-side or automated applications where no human interaction is possible. Use a client secret to authenticate directly.

curl -X POST https://api.zooza.app/v1/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-ZOOZA-API-KEY: your_api_key" \
  -d '{
    "login": "admin@example.com",
    "verification_method": "client_secret",
    "client_secret": "your_client_secret"
  }'
Important
  • The email must belong to a valid Zooza user with a role in the target company.
  • Use a user with the Owner role for full access.
  • Responses are always scoped to the user's role (e.g. a Lecturer only sees classes where they are assigned).

To obtain a client secret, contact Zooza support.

Getting the company ID​

Once you have a token, retrieve the company ID from the /v1/user endpoint.

curl -X GET https://api.zooza.app/v1/user \
  -H "X-ZOOZA-API-KEY: your_api_key" \
  -H "X-ZOOZA-TOKEN: your_token"

Response (abbreviated):

{
  "user_valid": true,
  "user": {
    "id": 1,
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "companies": [
      { "id": 65, "name": "Company A", "role": "member" },
      { "id": 76, "name": "Company B", "role": "owner" }
    ]
  },
  "app": {
    "application_id": 1,
    "company_id": 65,
    "type": "application"
  }
}

Use the id from the appropriate company in the X-ZOOZA-COMPANY header for subsequent requests.

Token lifecycle​

  • Tokens are long-lived but may be invalidated by Zooza at any time.
  • There is no explicit refresh mechanism — if a token becomes invalid, re-authenticate using one of the methods above.
  • Store tokens securely and handle 401 Unauthorized responses by re-initiating the login flow.