Zottle

Authentication

How the Zottle API authenticates its callers: web sessions, one-time codes, workspace API keys and field devices.

Base URL

Every endpoint in this reference is served on your Zottle address, with the /api prefix. Replace votre-serveur with the address of your own instance — the one you use in the browser.

https://<votre-serveur>/api

Sign in with email and password

POST /auth/login exchanges an email address and a password for a session. The email goes in the identifier field, the password in password. Google and Apple sign-in are also available: POST /auth/google and POST /auth/apple take an idToken issued by the provider.

curl -X POST https://<votre-serveur>/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"identifier":"you@example.org","password":"<your-password>"}'

The response carries the session and the refresh token. Use data.session.sessionTokenHash as the Bearer token on every call; keep data.refreshToken.refreshTokenHash to renew the session.

curl https://<votre-serveur>/api/users/me \
  -H "Authorization: Bearer $TOKEN"

A missing or invalid token is answered with 401 — the message reads authentication required, invalid or expired session, or session expired or revoked.

Warning

Never expose a session token in client-side code or a repository. Store tokens in a secret manager, and call the API from a server-side proxy when a browser is involved.

One-time codes by email

Zottle sends 6-digit codes by email. The same two endpoints serve email verification at sign-up and the password reset flow.

Method Endpoint Purpose
POST /auth/otp/generate Send a code to an email address. language picks the message template: en, fr or ar.
POST /auth/otp/verify Check a code. The response carries data.verified: true or false.

A code is valid for 10 minutes. After a successful check, the email address can be used to register for 15 minutes; a registration outside that window is refused with 400. Five failed checks lock verification for that address for 15 minutes.

Refresh a session

POST /auth/refresh takes the refresh token and returns a new session: a fresh Bearer token and a fresh refresh token. An unknown, revoked or expired refresh token is answered with 400, and the caller has to sign in again.

curl -X POST https://<votre-serveur>/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshTokenHash":"<refresh-token>"}'

Sign out

POST /auth/logout revokes a session. Send the session's Bearer token in the Authorization header, and the same session token in the sessionTokenHash body field.

curl -X POST https://<votre-serveur>/api/auth/logout \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"sessionTokenHash\":\"$TOKEN\"}"

Workspace API keys

A workspace can hold API keys with the zt_ prefix. Create one with POST /api-keys; the complete key is returned once, in the raw_key field of the response — copy it at that moment, it is never shown again. Zottle stores a SHA-256 hash of the key and keeps only a short prefix for identification.

Method Endpoint Purpose
POST /api-keys Create a key for a workspace. Body: name, workspace_id and optional scopes — read and write by default.
GET /api-keys List a workspace's keys — prefix, scopes and creation date. The secret is never returned.

These endpoints run under your session, like the rest of the API: API keys are created and listed for management, while requests to the API authenticate with the Bearer token described above.

Field devices (KoboCollect, ODK Collect)

Collect mobile clients sign in with HTTP Basic Auth — your Zottle email address and password — on the /mobile-collect endpoints. The first probe arrives without credentials and is answered with 401 and a WWW-Authenticate: Basic challenge; this is normal, it is how the app knows it must ask for a username and password.

Configure the server URL with no query string:

https://<votre-serveur>/api/mobile-collect

An anonymous collection link carries its token in the URL and never asks for credentials.